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About This Book 


Preface 


This book provides programming information you 
will need to use the IBM Personal Computer 3270 
Entry Emulator High-Level Language 
Application Program Interface (EEHLLAPI). 


EEHLLAPI is used with the IBM PC 3270 
Emulation Program, Entry Level (hereafter 
referred to as the Entry Level Emulation 
Program). 


EEHLLAPI gives users and application 
programmers a set of functions that can be called 
from an application program running in a 
personal computer session to access the host 
presentation space. 


If you just want to get started using the Entry 
Level Emulation Program or have no interest in 
using the programming interface, see the IBM 
PC 3270 Emulation Program, Entry Level, User’s 
Guide. 
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How This Book Is Organized 


e Chapter 1, “Introduction,” provides an 
overview of EEHLLAPI and discusses parts of 
the interface. 


e Chapter 2, “Loading the Program,” describes 
how to load the resident portion of 
EEHLLAPI and run the EKHLLAPI program 
sampler. 


e Chapter 3, “KEEHLLAPI Functions,” describes 
each function in detail. These functions are 
listed in alphabetical order. 


e Chapter 4, “Compiling and Running Your 
EEHLLAPI Application Program,” provides 
information about linking your EEHLLAPI 
program with the appropriate Language 
Interface Module (LIM), running your 
program, and using Trace. 


e Appendix A, “Messages,” explains the 
messages you may see while using 
EEHLLAPI. 


e Appendix B, “Writing Your Own Language 
Interface Module,” describes how you can 
write a Language Interface Module for any 
computer language you want to use beyond 
those supported by LIMs on your Entry 
Emulator diskette. 


e Appendix C, “OIA Image and Bit Group 
Information,” explains information needed to 
interpret the returned data string under 
Function 13 Copy OIA. 
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About This Book 


e Appendix D, “Related Publications,” refers 
you to IBM books that you might need. 


e Appendix E, “Sample Programs,” contains 
code samples. 


e Appendix F, “Glossary,” defines acronyms 
and terms used in this manual. 


e Appendix G, “Alternate Code Page Support,” 
lists the code pages supported for each 
country. 


Should Read This Book 


This book is intended for PC users and 
programmers who want to write application 
programs that use the services of EEHLLAPI. 


A working knowledge of the Personal Computer 
and IBM Personal Computer DOS is assumed. If 
you want more information about the Personal 
Computer, refer to the list of IBM Personal 
Computer publications in Appendix D, “Related 
Publications.” 


This book assumes you are familiar with the 
language and compiler you will be using. If you 
need more information on how to write, compile, 
or link-edit programs, refer to the appropriate 
reference books for the specific language. 
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Requirements 


Before you can use EEHLLAPI, you must 
understand the following hardware, software, and 
host computer requirements. 


Hardware Requirements 


EEHLLAPI is designed to operate on the IBM 
Personal Computer, the IBM Personal Computer 
AT, the IBM Personal Computer XT, the IBM 
Personal Computer XT Model 286, and IBM 
Personal System/2™ Models 25, 30, 50, 60, and 80. 
It requires approximately 12,000 bytes of storage 
in addition to the requirements for DOS and the 
Entry Level Emulation Program. 


Software Requirements 


The following software guidelines should help 
you use EEHLLAPI: 


e DOS Levels 3.2 and 3.3 are supported. 


e Level 1.21 of the Entry Level Emulation 
Program. 


e You must write your EEHLLAPI program in 
one of the following high-level languages (or 
its equivalent): 


— Compiled BASIC 1.0 or 2.0 

— Interpretive BASIC 2.1, 3.1, or 3.2 
— IBM COBOL 1.0 

— IBM C 1.0 

— IBM PASCAL 2.0. 


™ IBM Personal System/2 is a trademark of the 
International Business Machines Corporation. 
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— Macro Assembler. 


e Host graphics are not supported by 
EEHLLAPI. 


Note: For the latest information on available 
hardware and software that can be used 
with this product, see your authorized IBM 
Personal Computer dealer or local IBM 
representative. 


Compatibility with Other Emulation 
Products 


The Entry Level Emulation Program EEHLLAPI 
provides a subset of the programming functions 
offered by the IBM 3270 Personal Computer 
High-Level Language Application Program 
Interface. Programs written using EEHLLAPI 
can be run unchanged on a properly configured 
3270 PC. This compatibility provides for easy 
migration of programs from the IBM PC 3270 
Entry Level Emulation Program to the 3270 PC. 
Refer to the latest level of the IBM 3270 Personal 
Computer High-Level Language Application 
Program Interface, Programming Guide, for more 
details. 


Host Requirements 


There are no additional requirements other than 
those for the Entry Level Emulation Program. 
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Chapter 1. Introduction 


EEHLLAPI Overview 


The Entry Emulator High-Level Language 
Application Program Interface or EEHLLAPI 
(pronounced E-E hil-lappy) lets you write and use 
personal computer programs in IBM BASIC, 
PASCAL, COBOL, C, or Macro Assembler to 
interact with your host session. 


EEHLLAPYI is valuable in a variety of work 
environments. It can increase productivity for 
experienced users and provide a shorter learning 
curve for inexperienced users. 

1. It improves overall ease of use by: 


e Automating repetitive tasks 


e Masking complex applications from the 
user 


e Consolidating several complicated tasks 
into one simple task. 


2. It simplifies existing host applications. 
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3. It provides unattended operation, a 
programmed operator that monitors tasks 
without human intervention. This 
programmed operator could: 


e Monitor events that are serial in nature 
(for example, data center applications) 


e Automate console operation 
e Monitor response time and availability 
e Do stress testing. 


4. You can create composite screen 
applications using input from the host. The 
input for a composition screen is formatted 
and presented within a PC presentation 
space. 


5. You can write programs that divide the work 
between host and PC sessions. EEHLLAPI 
will let you write and use an application to 
access files and programs in either the host or 
the PC session. The more trivial tasks (file 
editing, simple graphics, etc.) can be done in 
the PC session and the more powerful host 
can do database searches, updates, and 
retrievals when needed. The terminal 
operator does not even need to know whether 
a PC or host application is doing the work. 
The goal is simply to finish the task. 


In other words, you can use EEHLLAPI with the 
functions provided by the Entry Level Emulation 
Program to enhance interaction between an IBM 
Personal Computer application program and a 
host session and to simplify your programming 
tasks. 
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What You Need to Get Started 


To use EEHLLAPI, you’ll need the following: 


1. The first thing you will need is an application 
program that you or someone else has written 
using IBM BASIC, COBOL, PASCAL, C, or 
Macro Assembler to call on the EEHLLAPI 
functions. If you don’t have one yet, you can 
try out the Program Sampler that is provided 
on the Entry Emulator diskette (see Chapter 2 
for more information). 


The other files that you’ll need are on your 
Entry Emulator diskette. 


2. PC3270.COM - this is the base Entry Emulator 
code. 


3. EEHLLAPI.EXE - this is the EEHLLAPI 
interface module. It lets your program 
interact with the base code. 


4. Except for interpretive BASIC, and assembly 
language programs, you will need one of the 
following Language Interface Modules 
(LIMs): 


e HLLC_S.oBJ - LIM for IBM “C” Language 
(small size) 


¢ HLLC_M.oBJ - LIM for IBM “C” Language 
(medium size) 


e HLLC.L.OBJ- LIM for IBM “C” Language 
(large size) 


e HLLCBAS.OBJ- LIM for Compiled IBM 
BASIC 


e HLLCOB.OoBJ- LIM for IBM COBOL 
e HLLPAS.oBJ- LIM for IBM PASCAL. 
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The LIM you choose depends on the 
programming language you intend to use. 
For example, if you were programming in 
COBOL, you would need the HLLCOB.OBJ 
file. (This book will explain how to use LIMs 
and how to write your own LIMs later on.) 


The Base Code (PC3270.COM) 


This is the code that provides the base emulation 
function on your IBM PC. It must be loaded 
before loading EEHLLAPI. 


The Resident Module 
(EEHLLAPI.EXE) 


The resident module for KEHLLAPI is called 
EEHLLAPI.EXE. It must be loaded before you 
can use KEHLLAPI and will remain in storage as 
an extension of DOS. 


Language Interface Modules (LIMs) 


LIMs are the “bridges” between your EEHLLAPI 
application program and EEHLLAPI.EXE. LIMs 
are provided because each implementation of a 
programming language has its own unique 
methods of storing data and calling subroutines. 
LIMS allow EEHLLAPI to support multiple 
high-level languages. 


LIMs are provided for Compiled IBM BASIC, 
IBM COBOL, IBM C, and IBM PASCAL. No 
LIM is required for Interpretive BASIC. Instead, 
you must access a special Interpretive BASIC 
LIM that is available whenever EEHLLAPI is 
loaded. Refer to Chapter 4, “Compiling and 
Running Your EEHLLAPI Application 
Program,” for details. 
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Programs written using the MACRO Assembler 
can invoke EEHLLAPI directly. If you prefer to 
use a language other than those mentioned 
above, refer to Appendix B, “Writing Your Own 
Language Interface Module.” 


Linking Your EEHLLAPI Program 
with Its LIM 


When you are ready to run your EEHLLAPI 
application program, you can make the 
appropriate LIM a permanent part of your 
program in this manner: 


e If you are using a compiled language (such as 
COBOL or Compiled BASIC), you call the 
appropriate language interface as an external 
subroutine. When you link-edit your program 
(using the DOS link command), the 
appropriate LIM will be merged with your 
EEHLLAPI program. Refer to 
Chapter 4, “Compiling and Running Your 
EEHLLAPI Application Program” for details. 


Function Calls 


EEHLLAPI is a “function-code”—driven system. 
This means that each EEHLLAPI function has a 
number associated with it. This number is the 
name you use to call the function from a program 
that you are writing. 
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Chapter 2. Loading EEHLLAPI 
and Running the Program 
Sampler 


This chapter tells you: 
e How to load EEHLLAPI 
e How to load and run the Program Sampler 


e How to load EEHLAPI automatically. 


Loading EEHLLAPI 


To load EEHLLAPI: 
1. Load DOS. 


2. Place the Entry Level Emulation Program 
diskette in your default diskette drive. 


3. Type PC3270 r next to the DOS prompt and 
press Enter ( <! ) to load the base code. 


Note: You must load the entry emulator in 
resume mode (r option when initially 
loading the PC3270 program, or type 
Alt-R while at the host when the 
PC3270 program is already loaded) 
before loading EEHLLAPI. 
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Loading EEHLLAPI 
4. Next, type eehllapi and press Enter ( # ) to 
load the EEHLLAPI code. 


Note: The base code must always be loaded 
first. 


When the program loads, you will see the 
following messages: 


Entry Emulator High Level Language Application Program Interface 1.1 


(c) Copyright International Business Machines Corporation 1984,1987 

EHLOO1 EEHLLAPI is loaded 

EHLOO2 EEHLLAPI is ready for use 

A> 
If you receive any other message refer to 
Appendix A, “EEHLLAPI Messages.” 
Note: If you want to load EEHLLAPI everytime 


you start your PC, see “Loading 
EEHLLAPI Automatically” on page 2-4. 


Installing and Running the 
Program Sampler 


After you have successfully loaded EEHLLAPI, 
you are ready to use the EEHLLAPI interface. 
The EEHLLAPI diskette contains a Complied 
BASIC Program Sampler (EHLSAMP.EXE) that 
lets you experiment with the various functions. 
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The Program Sampler allows you to specify a 
function and its parameters and observe the 
results. It also serves as an example of running a 
program written in BASIC in which the 
EEHLLAPI functions have been used. When you 
get ready to write your EEHLLAPI application 
program, you may find it useful to refer to the 
BASIC sample program in Appendix E, “Sample 
Programs” on page E-1. 


To run the Program Sampler EHLSAMP.EXE: 


1. Have your Entry Level Emulation Program 
and EEHLLAPI.EXE loaded into storage. 


2. Be sure that the following files are available 
to the program sampler (on the same diskette 
or in the same fixed disk directory): 


PC utilities that EHLSAMP uses, such as 


e Send.com 
e Receive.com. 


3. Place your Entry Level Emulator Program 
diskette which contains EHLSAMP.EXE in 
Drive A. 


4. Type ehlsamp and press Enter. You will see 
the EEHLLAPI Program Sampler panel 
appear. 


5. Sample the EEHLLAPI functions. 


It is a good idea to have the description of any 
function you sample (found in Chapter 3) in front 
of you as you use the Program Sampler. When 
you use the Program Sampler, you are using 
actual EEHLLAPI functions, not simulations of 
functions. All the rules about the order in which 
functions should be called apply when using the 
Program Sampler. For example, when using an 
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EEHLLAPI program, you must be connected to a 
session (by means of Function 1 Connect) before 
you can send keys to it (using Function 3 Send 
Key). 


If you want to quit a function without 
completing it, press Ctrl + Break. This will take 
you back to DOS. To use the EEHLLAPI 
Program Sampler again, type EHLSAMP and 
press Enter. 


When you are ready to exit the Program Sampler 
and return to DOS, type 300, and press Enter 
from main menu. 


For more information about using Compiled 
BASIC, refer to the IBM Compiled BASIC 
Reference Manual. 


Loading EEHLLAPI 
Automatically 


If you load your Entry Level Emulation Program 
using an AUTOEXEC.BAT file, you can also 
load EEHLLAPI automatically by adding a line 
to your AUTOEXEC.BAT file. Edit the 
AUTOEXEC.BAT file, using any editor that 
works on the personal computer. If you don’t 
have a standard personal computer editor, you 
can use the editor that comes with DOS (EDLIN). 
See your DOS manual for more details. 


To load KREHLLAPI using an AUTOEXEC.BAT 
file, add “eehllapi” following the “PC3270” 
statement, as follows: 


pc3270 r 
eehllapi 
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Preparing a Diskette 


If you want to use EEHLLAPI on an everyday 
basis, you will need to copy over certain files to 
your system diskette. The Install.bat file that is 
on the original diskette contains a list of all the 
files in the diskette along with comments that 
explain why the files are needed. To display this 
file on your screen, enter: 


type Install.bat 


To type this file to your PC printer, enter: 


type Install.bat>prn 
Copy the Install.bat file and use a PC editor 


(e.g., Personal Editor, EDLIN) to modify it to 
copy the files you need. 
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Page Layout Conventions 


All EEHLLAPI function calls are presented in 
the same format so that you can retrieve the 
information you need quickly. The format looks 
like this: 


Function Name 

e Parameters Required When Called 
e Values Returned 

e Notes on Using This Function. 


Parameters Required When Called 


“Parameters Required When Called” defines 
what parameters you need to define in your 
program in order to use this function and how 
these parameters are to be defined. 


EEHLLAPI function calls pass the following four 
parameters in this fixed format: 


A function number 

A data string 

The string’s length 

The host presentation space position. 
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Function Number, the first parameter, is 
always required. This position must be filled by 
a 2-byte (fullword) integer. 


Data String, the second parameter, is used in 
different ways by different functions. In some 
functions, the data string is a string of 
characters. In other functions, it is a string of 
concatenated data items. 


String Length, the third parameter, is usually 
the length of the character string or 
concatenated list of data items. In special cases, 
this parameter passes information such as buffer 
size. This position must be filled by a 2-byte 
(fullword) integer. 


Presentation Space Position, the fourth 
parameter, is a value associated with the IBM 
3278/79 Display Station screen sizes emulated by 
the PC. This position must be filled by a 2-byte 
(fullword) integer, and must be a value from 1 
through 1920 for the Entry Level Emulation 
Program. When the PS position is not 
applicable, this 2-byte integer may be any value. 


Values Returned 


“Values Returned” defines the information that 
your program will receive from EEHLLAPI after 
EEHLLAPI has processed your function call. 


EEHLLAPI function calls return requested 
information in the following format: 


e Function number 

e Data string 

e Data string length or host presentation space 
position 

e Return code. 
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Note that not all four parameters will be 
changed on return for each function. 


Function Number, the first parameter, is 
always returned unchanged. 


Data String, the second parameter, returns 
different information according to function. In 
some functions, the data string is a string of 
characters. In other functions, it is a string of 
concatenated data items. 


You must preallocate space for returning data 
strings in your EEHLLAPI application program. 


The third parameter, when sending data to 
EEHLLAPYI, is interpreted as Data Length. For 
certain function calls EEHLLAPI returns a 
presentation space position (this is a numeric 
value 1 through 1920). 


Return Code, the last parameter, is usually a 
numeric return code. Function 99 Convert 
Position or RowCol is the exception to this 
rule. In Function 99, the return code position 
passes data to the program. 


Return codes are explained in detail in the 
descriptions of the individual functions. 


Notes on Using This Function 


“Notes On Using This Function” explains any 
prerequisite function calls that should be issued 
before using the function under discussion. It 
also provides technical information about using 
the function and application development tips. 


See Appendix E, “Sample Programs” for 
examples on how the functions are used. 
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Connect Presentation Space (1) 


Connect Presentation Space establishes a 
connection between your KEHLLAPI application 
program and the host presentation space. 


Parameters Required When Called 


Data String: One-character short name of the 
host presentation space.* 
Length: NA (1 is implied). 


PS Position: NA 
*The calling data string can contain: 


e A one-character host presentation space short 
name. 


e For the Entry Level Emulation Program, the 
default presentation space is “E”. 


Note: If you are using this default, you must 
have an “E” in the calling data string. 


3-4 Programming Guide 


Connect Presentation Space 


Values Returned 


The following return codes are valid: 


Return 
Code Explanation 
Connect was successful; the host presentation space 
is unlocked and ready for input. 
An invalid host presentation space id. 


4 Successful connection was achieved, but the host 
presentation space is busy. 


5 Successful connection was achieved, but the host 
presentation space is locked (input inhibited). 
9s A system error was encountered. 


li This resource is unavailable. The host presentation 
space is already being used by another system 


function. 


Notes on Using This Function 


1. The following functions do not require that 
you issue a Connect call before using: 


Function 9 Set Session Parameters 
Function 10 Query Sessions 

Function 20 Query System 

Function 21 Reset System 

Function 22 Query Session Status 
Function 24 Query Host Update 
Function 90 Send File 

Function 91 Receive File 

Function 99 Convert Position or RowCol 


2. The Connect Presentation Space function 
sets the return code to indicate the status of 
the attempt and, if successful, the status of 
the host presentation space. 
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3. Two parameters under Function 9 affect 
Connect: 


Explanation 
CONPHYS During the Connect, jump to the requested presentation 
space (Do a physical connect). 
CONLOG During the Connect, do not jump to the requested 
presentation space (Do a logical connect). 
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Convert Position or RowCol (99) 


This function converts the host presentation 
space positional value into the display 
row/column coordinates or converts the display 
row/column coordinates into the host 
presentation space positional value. This 
function does not change the cursor position. 


Parameters Required When Called 


Data String: Host Presentation space short 
name and “P” for convert 
position, OR 


Host presentation space short 
name and “R” for convert 
row/column. 

Length: Row 

PS Position: Column (when specify “R” 
above) or host presentation 
position (when specify “P” 
above). 


Values Returned 


The function is the exception to the rule that the 
return code position always contains a return 
code. In this instance, it contains a status code. 
If you have established a common error-handling 
routine, this function could return misleading 
information. 
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Two pieces of information are returned: 


e The Length parameter which returns the row 
number or “0” for incorrect row input. 


e A status code in the Return Code parameter 
which is explained below: 


Explanation 
Incorrect column or presentation space position was 
provided. 


>0 This is the PS position or column. 
9998 An invalid host presentation space ID was specified, 
or the host presentation space was never connected. 


9999 Character 2 in the data string is not P or R. 
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Copy Field to String (34) 


The Copy Field to String function transfers 
characters in the host-connected presentation 
space into a string. The string begins at the 
field’s origin delimiter. This position and length 
information can be found by using Function 31 
Find Field Position and Function 32 Find Field 
Length. This function can be used with either 
protected or unprotected fields but only in a 
field-formatted host presentation space. 


The string ends when one of these three 
conditions is encountered: 


e When the end of the field is reached 

e When the length of the target string is 
exceeded 

e When the end of the host presentation space 
is reached. 


Parameters Required When Called 


Data String: Preallocated target data string. 

Length: Length of the target data string. 

PS Position: Position of the source field in 
the host presentation space from 
which to copy. 
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Values Returned 


This function returns the requested data string 
and one of the following return codes: 


Return 
Code Explanation 


Copy Field to String was successful. 


Your program is not currently connected to the emulated host 
session 


oT An error was made in specifying parameters. 
Eo The data to be copied and the target field were not the same size. 


The data may have been truncated because the string length may 
have been smaller than the field copied. 


The host presentation space position is invalid. 
A system error was encountered. 
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Copy OIA (13) 


*The Copy OIA function returns the current 
OIA data from the host connected presentation 
space. 


Parameters Required When Called 


Data String: Target string 

Length: Length of the target data 
string.* 

PS Position: NA 


*The OJA data is returned in a data string that 
must be 103 bytes long. The format of the 
returned string is as follows: 


Byte 
Position 1 The OJA Format Byte for the PC. 

Positions 2-81 The OIA image in host code points. Refer to 

Appendix C, “OIA Image and Bit Group Information” for 
complete explanations of these positions. 

The OJA Group. Refer to Appendix C, “OJA Image and 


Bit Group Information” for complete explanations of 
these positions. 


Positions 82-103 
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Values Returned 


Return 
Code Explanation 


The target presentation space is unlocked. 


1 Your program is not currently connected to the emulated host 
session. 

2 An error was made in specifying string length. OIA data was not 
returned. 


OIA data was returned. The target presentation space is busy. 
OIA data was returned. The target presentation space is locked. 


An internal system error was encountered. OIA data was not 
returned. 
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Copy Presentation Space (5) 


The Copy Presentation Space function copies 
the contents of the host-connected presentation 
space into a data area that you define in your 
EEHLLAPI application program. 


Copy Presentation Space translates the 
characters in the host source presentation space 
into ASCII. Attribute bytes and other characters 
not represented in ASCII normally are translated 
into blanks. (If you do not want the attribute 
bytes translated into blanks, you can override 
this translation with the ATTRB option under 
Function 9 Set Session Parameters.) 


Parameters Required When Called 


Data String: Preallocated target area the size 
of your host presentation space. 
This is 1920 for Entry Level 
Emulation Program. 


Length: NA (length of the presentation 


space is implied) 
PS Position: NA 


Chapter 3. EEHLLAPI Functions 3-13 


Copy Presentation Space 


Values Returned 


Return 
Code Explanation 


The host presentation space contents were copied to application 
program. The target presentation space was active, and the 
keyboard was unlocked. 


1 Your program is not currently connected to the emulated host 
session. 


host presentation space was waiting for host response. 
La A system error was encountered. 


Notes on Using This Function 


e A program written in Interpretive BASIC 
cannot use this function, since copying the 
host presentation space exceeds the maximum 
allowed string size of 255 bytes. Compiled 
BASIC programs, however, can use this 
function. 


e If you want to copy only a portion of the host 


presentation space, use Function 8 Copy 
Presentation Space to String. 
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Copy Presentation Space to 
String (8) 


The Copy Presentation Space to String 
function is used to copy all or part of the 
host-connected presentation space into a data 
area that you define in your EEHLLAPI 
application program. 


The offset of the string into the host presentation 
space is based on a layout in which the upper left 
corner (row 1/column 1) is Location 1 and the 
bottom right corner is the maximum screen size 
for the host presentation space (for the Entry 
Level Emulation Program, for example, this 
would be 1920). The value of offset + length 
cannot exceed the maximum screen size for the 
host presentation space. 


The “PS Position” calling parameter is used to 
pass the beginning offset of the data string to the 
function. The maximum length of the target 
string is 255 bytes for Interpretive BASIC. The 
requested length must not exceed the length of 
your application program’s preallocated buffer 
size. 


Copy Presentation Space to String translates 
the characters in the host source presentation 
space into ASCII. Attribute bytes and other 
characters not represented in ASCII normally are 
translated into blanks. If you do not want the 
attribute bytes translated into blanks, you can 
override this translation with the ATTRB option 
under Function 9 Set Session Parameters. 
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Parameters Required When Called 


Data String: Target string (maximum 
255 bytes for Interpretive 
BASIC). 
Length: Length of the target data string. 
PS Position: The beginning of your string is 


represented by the byte position 
within the host presentation 
space. 


The value of Position + Length cannot exceed 
the maximum size of the host presentation space. 
This value cannot exceed 1920 for the Entry 
Level Emulation Program. 


Values Returned 


The Copy Presentation Space to String 
function returns a string containing the host 
presentation space contents and one of the 
following return codes: 


Return 
Code Explanation 


The host presentation space contents were copied to application 
program. The target presentation space was active, and the 
keyboard was unlocked. 


Your program is not currently connected to the emulated host 
session. 


An error was made in specifying string length. 


The host presentation space contents were copied. The host 
presentation space was waiting for host response. 

The host presentation space was copied. The keyboard was locked. 
The host presentation space position is invalid. 


A system error was encountered. 
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Copy String to Field (33) 


The Copy String to Field function transfers a 
string of characters into a specified field in the 
host-connected presentation space. This function 
can be used only in a field-formatted host 
presentation space. 


The string to be transferred is specified with the 
Calling Data String parameter. The string ends 
when one of these four conditions is encountered: 


e When an EOT is encountered in the string 
(Gif EOT mode was selected using Function 9 
Set Session Parameters). See “Set Session 
Parameters (9)” on page 3-65. 


e When the number specified in the length is 
reached if not in EOT mode. 


e When an end of field is encountered in the 
field. 


e When the end of the host presentation space 
is reached. 


In other words, there is no wrapping. 


Parameters Required When Called 


Data String: String containing the data to be 
transferred to a target field in 
the host presentation space. 

Length: Length of the source data string 
or an KOT in the data string if 
in KOT mode. 

PS Position: Position of the field that is the 
target of the copy. 
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Values Returned 


Return 
Code Explanation 


Copy String to Field was successful. 


1 Your program is not currently connected to the emulated host 
session. 

5 The target field was protected or inhibited, or illegal data was sent 
to the target field (such as a field attribute). 


Copy was completed, but data is truncated. 
The host presentation space position is invalid. 
A system error was encountered. 
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Copy String to Presentation 
Space (15) 


Copy String to Presentation Space copies an 
ASCII data string directly into the host 
presentation space at the location specified by 
the “PS Position” calling parameter. 


Parameters Required When Called 


Data String: String of ASCII data to be 
copied into the host 
presentation space. 


Length: Length of data string or an EOT 
in data string if in EOT mode. 
PS Position: Position in the host 


presentation space to begin the 
copy; between 1 and 1920 for the 
Entry Level Emulation 
Program. 


Values Returned 


Return 

Code Explanation 
Copy String to Presentation Space was successful. 
Your program is not currently connected to the 
emulated host session. 


The target presentation space is protected or 
inhibited, or illegal data was sent to target 


presentation space (such as a field attribute byte). 


The copy was completed, but the data was truncated. 
The host presentation space position is invalid. 
A system error was encountered. 
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Notes on Using This Function 


e If you want to place the string data at a 
specific cursor location, use Function 7 
Query Cursor Location first to get the PS 
Position of the cursor. Then place this value 
in the “PS Position” calling parameter. 


e The string ends when an EOT is encountered 
in the string (if EOT mode was selected using 
Function 9 Set Session Parameters). See 
“Set Session Parameters (9)” on page 3-65. 


e Even though Function 3 Send Key seems to 
accomplish the same purpose as Copy String 
to Presentation Space, the latter is much 
faster in answering prompts and entering 
commands. The concept behind the Send 
Key function is to emulate a terminal 
operator typing in data from the keyboard. 
Thus, it is too slow for applications that 
require large amounts of data for each 
operation. Copy String to Presentation 
Space provides a much faster input path to 
the host. 


e The keyboard mnemonics (see Function 3 
Send Key) cannot be sent using Copy String 
to Field. 


e The source data (the string being copied) can 
be no larger that 1920 characters. 
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Disconnect Presentation Space (2) 


Disconnect Presentation Space drops the 
connection between your EKHLLAPI application 
program and the host presentation space. 


Parameters Required When Called 


Data String: NA 
Length: NA 
PS Position: NA 


Values Returned 


Explanation 


i i Disconnect was successful. 
1 You are not currently connected to the host 
presentation space. 


A system error was encountered. 


Notes on Using This Function 


e Once the Disconnect Presentation Space 
function has been called, functions that 
interact with the host presentation space are 
no longer valid (for example, Send Key, Wait, 
Reserve, and Release). 


e Your programmed operator should disconnect 
from the host presentation space before 
exiting your EEHLLAPI application program. 
Failure to do so can result in problems 
when using some PC utilities, particularly 
file transfer. 
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e Disconnect Presentation Space does not 
reset the session parameters to the defaults. 
Your programmed operator must call 
Function 21 Reset System to accomplish 
this. For example, a keyboard locked using 
the Reserve function will remain locked after 
the application has been disconnected. 


e Two parameters under Function 9 affect 
Disconnect: 


Explanation 


CONPHYS During the Disconnect, jump to the PC session where the 
EEHLLAPI application is running (Do a physical 


disconnect). 


CONLOG During the Disconnect, do not jump to the PC session. Stay 
at the current presentation space — could be at the HOST or 


PC (Do a logical disconnect). 
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Find Field Length (82) 


Find Field Length returns the length of a target 
field in the connected presentation space. This 
function can be used to find either protected or 
unprotected fields but only in a field-formatted 
host presentation space. 


This function returns the number of characters 
contained in the “Requested Field.” This includes 
all characters from the beginning of the target 
field up to either the character preceding the 
next attribute byte or the end of the host 
presentation space. 


Parameters Required When Called 


Data String: See table below. 

Length: NA (2 is implied). 

PS Position: Position within the host 
presentation space from which 
to start the Find. 


The calling two-character data string can 
contain: 


Explanation 


Blanks | This field 
“mp ” 


or 
|“P_” __| The previous field, either protected or unprotected | 
|“PP” | The previous protected field 
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Values Returned 


Length: = 0 means PC or unformatted 
host presentation space. 
> 0Omeans length of requested 
field in host presentation 
space. 


Return Code: The following are valid: 


Return 
Code Explanation 


Find Field Length was successful. 


Your program has not issued a CONNECT to the 
emulated host session. 


fo 
aed 


The host presentation space position is invalid. 
A system error was encountered. 
No such field was found. 
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Find Field Position (31) 


Find Field Position returns the beginning 
position of a target field in the host connected 
presentation space. This function can be used to 
find either protected or unprotected fields but 
only in a field-formatted host presentation space. 


Parameters Required When Called 


Data String: See table below. 

Length: NA (2 is implied). 

PS Position: Position (within the field) 
relative to the origin of the host 
presentation space at which to 
start the Find. 


The calling two-character data string can 
contain: 


Blanks | This field 
or 
ad Wy ” 


The previous field, either protected or unprotected 


> 
NO 
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Values Returned 


Length: = 0 means unformatted 

presentation space. 

> 0 means relative position of 
requested field from the 
origin of the host 
presentation space. This 
position is defined to be the 
first position after the 
attribute byte. 


Return Code: The following are valid: 


Return 
Code Explanation 


Find Field Position was successful. 


Your program has not issued a CONNECT to the 
emulated host session. 


jo 
ae 


The host presentation space position is invalid. 
A system error was encountered. 
No such field was found. 
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Pause (18) 


Pause waits for a specified amount of time. It 
should be used in place of “timing loops” to wait 
for an event to occur. A Pause may be ended by 
a host event if a prior Function 23 Start Host 
Notification had been called. 


Parameters Required When Called 


Data String: NA 

Length: Contains the pause duration in 
half-second increments.* 

PS Position: NA 


*A practical maximum value for Pause is 2400. 
You should not use Pause for these kinds of 
tasks: 


e Delay for very long durations (of several 
hours, for example) 


e Delay for more than a moderate length of 
time (20 minutes) before checking the system 
“time of day” clock and proceeding with your 
EEHLLAPI program execution 


e With applications requiring a high-resolution 
timer. Since the time interval created by a 
Pause is approximate, such applications 
should use an alternate timing method. 
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Values Returned 


Return 
Code Definition 


fo The wait duration has expired. = zs 


An internal system error was encountered. The time results are 
unpredictable. 


A host session presentation space or OIA been updated. Use 
Function 24 Query Host Update for more information. 


Notes on Using This Function 


One of the parameters set using Function 9 Set 
Session Parameters affects the length of the 
pause you get when you call this function. 


Explanation 


| FRAUSE Full-durationpause, 


Interruptible pause. Function 23 Start Host Notification 
and a host event will satisfy a Pause. 
Once a pause has been satisfied by a host event, 
you must call Function 24 Query Host Update 
to obtain more data regarding the host PS/OIA 
update prior to the next Pause. If you use the 
IPAUSE option, Pause will continue to be 


satisfied with the pending event until Function 
24 Query Host Update is completed. 
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Query Cursor Location (7) 


The Query Cursor Location function indicates 
the position of the cursor in the host-connected 
presentation space by returning the cursor 
position. 


Before you can call Query Cursor Location, 
you must be connected to the host presentation 
space. 


Parameters Required When Called 


Data String: NA 
Length: NA 
PS Position: NA 


Values Returned 


Length: Presentation space position of 
the cursor. 


Return Code: One from the table below: 


Return 
Code Explanation 


ro Query Cursor Location was successful. 

1 Your program is not currently connected to the 
emulated host session. 
poo A system error was encountered. 
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Query Field Attribute (14) 


The Query Field Attribute function returns the 
attribute byte of the field containing the host 
presentation space position in the host connected 
presentation space. This information is returned 
as the “Returned Data Length” parameter. Note 
also these use characteristics: 


e The returned Data Length parameter is set to 
“0” if the screen is unformatted. 


e Attribute bytes are equal to or greater than 
hex CO. 
Parameters Required When Called 
Data String: NA 


Length: NA 

PS Position: Presentation space position in 
the connected presentation 
space 


Values Returned 


Length: The Attribute value or “0” if the 
screen is unformatted. 
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Return Code: The following are valid: 


Return 
Code Explanation 
Query Field Attribute was successful. 


1 Your program has not issued a CONNECT to the 
emulated host session. 
The host presentation space position is invalid. 
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Query Host Update (24) 


The Query Host Update function lets the 
programmed operator determine if the host has 
updated the host PS/OIA since the last time this 
request was made. The target presentation space 
must be specified in the data string, even though 
you don’t need to be connected to the host 
presentation space to check for updates. 


The Start Host Notification function must be 


called before your programmed operator can use 
the Query Host Update function. 


Parameters Required When Called 


Data String: One-character short name of the 
host presentation space. 
Length: NA (1 is implied). 


PS Position: NA 


Values Returned 


Return 
Code Definition 


No updates have been made since the last call. 

An invalid host presentation space was specified, one that was 
labeled with an invalid name. 

No prior Start Host Notification function was called for the host 
presentation space ID. 


The OIA was updated 


The presentation space was updated. 


The OIA and the host presentation space were updated. The Entry 
Level Emulation Program can not distinguish between OIA and 
presentation space updates. 


aioe 
[a _| A system error was encountered, SSCS 
Eel 
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Query Session Status (22) 


Query Session Status provides session-specific 
information. 


Parameters Required When Called 


Data String: Short name of the target 
presentation space plus 17 bytes 
for returned data 

Length: 18 bytes 

PS Position: NA 


Values Returned 


Data String 


A data string of 18 bytes is returned. The bytes 
are defined below. 


Position 1 Short name (PSID). This can contain: 


@ The one-letter short name of the host presentation 
space 


A blank or null indicating a function call against the 
host presentation space (if connected). 


If a “generic” request has been made, the actual PSID will 
be substituted in the string that is returned. 


Session type (where C = CUT Host) 
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For the Entry Emulator the returned value will always be 0. 


Position 12 Number of rows in the host presentation space, expressed as 
a binary number. 
Position 14 Number of columns in the host presentation space, expressed 
as a binary number. 
Positions Reserved 
16-17 


Return Codes 


Return 

Code Explanation 
Query Session Status was successful. 
The session requested was invalid. 


An invalid string length was made. This code will not be returned 
for all programming languages. 


A system error was encountered. 
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Query Sessions (10) 


Query Sessions, in the case of the Entry 
Emulator, returns a 12-byte data string 
describing the host session. The data string 
contains the short name, session type, and 
presentation space size of the host session. 


If this function is to be used in 3270 PC 
applications as well as in Entry Emulation 
applications, you should know that this function 
will return one 12-byte descriptor for each 
session type available (excluding WS CTRL). 
This means a potential 144 bytes could be 
returned (12 sessions X 12 bytes) in a 3270 PC 
environment. 


Parameters Required When Called 
Data String: Preallocated string of 12 bytes. 
Length: From 12 to 144 bytes. 
PS Position: NA 

Values Returned 
Data String 
The returned data string contains the short 


name, host session type, and PS size of the host 
session. 
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The format of each 12-byte session descriptor is 


as follows: 


Positions 2-9 Long name of session. For Entry Level Emulation 
Program this is HOST1. 

Position 10 Session type (H=host). For 3270 PC N=Notepad and 
P=PC. 

Positions 11-12 Host presentation space size (this is a binary number and 
is not in display format) 


Length 


The number of configured sessions will always be 
1 for the Entry Level Emulation Program. 


Return Code: The following are valid: 


Return 
Code Explanation 


fo Query Sessions was successful. 


An improper string size was specified; the string is too small. 
(Note that here and in other functions the ability to verify actual 
string size is language dependent.) 


A system error was encountered. 


Notes on Using This Function 


A maximum of 1 session (host) can exist in an 
Emulator environment. 
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Query System (20) 


An EEHLLAPI application program can use 
Query System to determine the level of the 
Entry Level Emulation Program support and 
other system-related values. This function 
returns a string with the appropriate system 
data. Most of this information is for use by a 
service coordinator when you call the IBM 
Support Center after receiving a Return Code 9 
(a system error was encountered). 


The bytes in this returned string are defined 
below under “Values Returned.” 


Parameters Required When Called 
Data String: Preallocated string of 35 bytes. 
Length: NA (Implied length is 35). 
PS Position: NA 

Values Returned 
Data String 


A data string of 35 bytes is returned. The bytes 
are defined as follows: 


Byte Definition 


Position 1 EEHLLAPI version number 


EEHLLAPI level number 


EEHLLAPI date (month, date, year—for service purposes 
only) 


Position 10 LIM version number (only valid for LIMs provided on the 
_ Entry Emulator diskette; otherwise, LIM number = 0) 
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Positions 11-12 LIM level number 


Position 13 Hardware base, where P= PC or PC XT, A= Personal 
Computer AT, and U = Unable to Determine 
Position 14 Control program type, where E= Entry Emulator. 


Position 15 Control program level, where if an E is returned, then 
1=1.XX. 


Position 16 


Positions 17-18 NLS table code for 3270 PC. Reserved for Entry 
Emulator. 


Position 19 


Positions 20-23 Extended Error Code 1. This is a printable ASCII string 
representing a hex word giving the EEHLLAPI 
component ID and system error number for that function 
(for service purposes only). 


Positions 24-27 Extended Error Code 2. This is a printable ASCII string 
representing a fault symptom code for the last internal 
system error.* 


Positions 28-35 Reserved. 


*In general, extended error codes represent 
internal diagnostic information, such as the 
contents of the computer register which 
indicated the system error and contained the bad 
internal code. 


Return Codes 


Explanation 


Query System was successful; data string has been returned. 


2 Improper string size (string too small). Note that here and in other 
functions the ability to verify actual string size is language 
dependent. 


Poe A system error was encountered. 
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Notes on Using This Function 


Your EEHLLAPI program should include a 
check of the return code for all function calls as 
a prerequisite for continuing your program. 


e Ifthe return code is good, the program should 
continue. 


e Ifthe return code is “9” (system error), your 
EEHLLAPI program should call a subroutine 
that requests Function 20 Query System. 
The subroutine could extract extended error 
code information to help your service 
coordinator determine the cause of the system 
error. When you contact your service 
coordinator, be prepared to give the 
system-error information generated by 
Function 20. 
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Receive File (91) 


Receive File is used to receive a file from the 
host session to the PC session. It is used the 
same way as the “receive” command is used in 
the Entry Level Emulation Program. However, 
the Receive File function may be called by an 
EEHLLAPI application program. 


Parameters Required When Called 


Data String: The same receive parameters as 
are usual for an Entry Level 
Emulation Control Program file 
transfer request. 


Length: Length of the data string or 
EOT in the data string. 
PS Position: Drive number 


The drive number indicates the location of the 
RECEIVE.COM file, where: 


Drive A = 1 
Drive B = 2 
Drive Z = 26 


If RECEIVE.COM is located on a fixed disk, the 
file must be in the current subdirectory. 
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Values Returned 
You can receive three kinds of return codes: 
1. EEHLLAPI Return Codes 


If a problem was encountered with the way 
you specified your data string or with the 
system, you would receive one of these return 
codes: 


Return 
Code Explanation 
You have specified a data string length that is too long for the 
EEHLLAPI buffer. The file transfer was unsuccessful. 
HOES sl A system error was encountered. 


2. File Transfer Message Codes 


The message number of the Entry Level 
Emulation Program file transfer messages 
may be returned. For example, if you are 
using the Entry Level Emulation Program, 
file transfer message “TRANS003 File transfer 
complete” would send back a return code of 3. 
For a complete list of the file transfer 
messages, refer to Appendix A in the IBM PC 
8270 Emulation Program, Entry Level, User’s 
Guide. 


An example of a message you might receive is 
listed below: 


Return 
Code Explanation 
File transfer complete. 


Chapter 3. EEHLLAPI Functions 3-41 


Receive File 


3. DOS Extended Error Codes 


DOS extended error codes are preceded by the 
number “3” (added by EEHLLAPI). To 
determine the DOS extended error code, 
subtract 300 and reference the JBM DOS 
Technical Reference Guide. 


Notes on Using This Function 


1. You must not be currently connected or have 
the session reserved before using Receive 
File. If you are linked to the host session 
already, you will receive File Transfer 
Message 7, “Cannot link to host: file transfer 
cancelled.” 


Therefore: 


e Ifyou are connected (with Function 1 
Connect Presentation Space) to the host 
session, you must disconnect (using 
Function 2 Disconnect Presentation 
Space). 


e If you have reserved (with Function 11 
Reserve) the host session, you must 
release it (using Function 12 Release). 


2. Special considerations for providing a path 
back to COMMAND.COM exist when you use 
this function. 


The parent application (KEHLLAPI) causes a 
subprocess program (like RECEIVE.COM) to 
be loaded, and the subprocess program 
inherits the parent’s environment. The 
EEHLLAPI environment segment contains 
the path back to the COMMAND.COM used 
when EEHLLAPI was loaded. 
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Explanation 


QUIET Keeps SEND and RECEIVE messages from being 
displayed. EEHLLAPI will keep track of the message 
number and discard the message. 


NOQUIET Restores the display of messages. 


Receive File 


While some subprocess applications are 
running, COMMAND.COM may be overlaid 
and may have to be reloaded. Therefore, the 
COMMAND.COM must be available on the 
same path as EEHLLAPI. 


It also means that RECEIVE.COM must be in 
the current directory when you issue a call to 
Function 91 RECEIVE File. This is not 
necessarily the root directory or the directory 
in use when EEHLLAPI was loaded, all of 
which may be changed by the time the 
Receive File function is executed. 
RECEIVE.COM must be in the current 
directory. 


Two sets of parameters under Function 9 Set 
Session Parameters are related to this 
function: 


Explanation 


TIMEOUT =N 


A one-character indicator from the table below will tell 
EEHLLAPI how many 30 second cycles (how many 
messages with TRANSO10) it should accept before issuing 
a CTRL+ BREAK itself. 


Character Value Character Value 
(in (in 
minutes) minutes) 


-0 
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Explanation 


TIMEOUT =0 Timeout messages will be displayed every 30 seconds 
until the operator presses CTRL+ BREAK (these 
messages would not be visible in the QUIET mode). This 
is standard for operator usage of SEND and RECEIVE. 


Considerations for Using 
Functions 90 and 91 


Functions 90 and 91 provide powerful additional 
abilities to high-level language applications, but 
they may require some effort to be usable in the 
language in which you choose to write your 
EEHLLAPI program. 


This is because when DOS loads a program, it 
normally loads it so that a new program “owns” 
all of memory from the Program Segment Prefix 
(PSP) to the highest end of memory, including 
the memory occupied by COMMAND.COM 
(which contains the loader). 


A well-behaved program uses the DOS 
SETBLOCK function call when it receives 
control froom COMMAND.COM to shrink its 
allocated memory block down to the size it really 
needs. This action frees unneeded memory, which 
can then be used for loading subsequent 
programs (and the loader, if necessary). 


You should also be aware that the MAX ALLOC 
field and MIN ALLOC field parameters in the 
EXE file header affect the memory size. 
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Functions 90 and 91 can only operate if there is 
enough free memory for the appropriate program 
to be loaded. If insufficient space is available, 
EEHLLAPI will return a 308 return code 
(“Insufficient memory”). In general, Interpretive 
BASIC and C do not occupy all of memory but 
may still produce a 308 return code if sufficient 
memory is not available for the subsequent 
program. 


If left unchanged, Compiled BASIC, PASCAL, 
and COBOL, when linked with their appropriate 
LIMS and loaded, will be given all of the 
available memory in the DOS session. Since 
there is no uniform way for EKEHLLAPI to 
perform a SETBLOCK function for all languages 
and all situations, it does not do it. It is your 
responsibility to implement the DOS SETBLOCK 
function (DOS interrupt X‘21’ AH=X‘4A’) 
suitable to your high-level language to shrink 
the application module to a minimum size so that 
SEND.COM and RECEIVE.COM can be 
executed. 


For more information, refer to the IBM Personal 


Computer Disk Operating System Technical 
Reference. 
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Release (12) 


Release unlocks the host presentation space that 
was reserved using Function 11 Reserve. 


Parameters Required When Called 


Data String: NA 
Length: NA 
PS Position: NA 


Values Returned 


Return 
Code Explanation 


Release was successful. 


1 Your EEHLLAPI program is not connected to a valid host 
presentation space 


A system error was encountered. 


Notes on Using This Function 


If you forget to Release a reserved host 
presentation space (reserved by using Function 
11 Reserve) before ending your EEHLLAPI 
application, you will be locked out of that 
session until another application releases it or 
until you call Function 21 Reset System. 
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Reserve (11) 


Reserve locks the host presentation space to 
prevent input from the terminal operator. 


The reserved host presentation space remains 
locked until it is either unlocked by Function 12 
Release or Function 21 Reset System. 


Parameters Required When Called 


Data String: NA 
Length: NA 
PS Position: NA 


Values Returned 


Return 
Code Explanation 


Reserve was successful. 


1 Your EEHLLAPI program is not connected to the host 
presentation space. 


A system error was encountered. 


Notes on Using This Function 


If your EEHLLAPI application program is 
sending a series of transactions to the host, you 
may need to prevent the user from gaining access 
to that session until your application processing 
is complete. 
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Reset System (21) 


The Reset System function reinitializes the 
resident interface module EKEHLLAPI. Event 
notification is stopped. The session parameter 
options are reset to their defaults. The reserved 
host session is released. The host presentation 
space is disconnected. 


You can use Reset System during initialization 
or at program termination to reset the system to 
a known initial condition. 


Parameters Required When Called 
Data String: NA 


Length: NA 
PS Position: NA 


Values Returned 


Return 

Code Definition 
fo Reset System was successful. 
[9 | A system error was encountered. 
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Search Field (30) 


Search Field examines a field within the 
connected host presentation space for the 
occurrence of a string. If the target string is 
found, this function returns the decimal position 
of the string numbered from the beginning of the 
host presentation space. (For example, the “row 
1, column 1” position is numbered “1”, or the 
“row 5, column 1” position is numbered “321”.) 


This function can be used to search for either 
protected or unprotected fields but only in a 
field-formatted host presentation space. 


This function returns “0” if the string is not 
found. 


Parameters Required When Called 


Data String: Target string for search. 

Length: Length of the target data string 
or an EOT in the data string if 
in KOT mode. 

PS Position: Position within the host 
presentation space where the 
search is to begin. Valid only if 
SRCHFROM parameter has 
been specified using Function 9, 
Set Session Parameters. 
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Values Returned 


Length: 


0 means that the string was 
not found. 

> 0 means that the string was 
found at the host 
presentation space position. 


Return Code 


Return 
Code Explanation 


Search Field was successful. 


Your program has not issued a CONNECT to the 
emulated host session. 


The host presentation space position is invalid. 


A system error was encountered. 


The search string was not found, or the screen was 
unformatted. 


Notes on Using This Function 


Two sets of parameters under Function 9 Set 
Session Parameters related directly to search 
operations: 


Explanation 
SRCHALL Search will scan the entire host presentation space. 
SRCHFROM Search will start from a specified beginning position. 


SRCHFRWD Search will be performed in an ascending direction. 


SRCHBKWD | Search will be performed in a descending direction. A 


Search will be satisfied if the first character of the requested 
string starts within the bounds specified for the Search. 
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You can use Function 9 Set Session 
Parameters to determine whether your searches 
will search forward (SRCHFRWD) or search 
backward (SRCHBKWD). This is important 
because search will not wrap from the bottom of 
the screen to the top. 
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Search Presentation Space (6) 


Search Presentation Space lets your 
EEHLLAPI program examine the host 
presentation space for the occurrence of a 
specified string. 


Parameters Required When Called 


Data String: Target string of Search. 

Length: Length of the target data string 
or an EOT in the data string if 
in EOT mode. 

PS Position: Position within the host 
presentation space where the 
search is to begin. Valid only if 
SRCHFROM parameter has 
been specified using Function 9, 
Set Session Parameters. 


Values Returned 


Length 0 means that the string was 

not found. 

> 0 means that the string was 
found at the host 


presentation space position. 
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Return Code 


Explanation 


Poh Sd Search Presentation Space was successful. 
The host presentation space was not connected. 


An error was made in specifying parameters (for 
example, the EOT character was specified under 
Set Session Parameters, but not found in the 
data string). 


7 The host presentation space position is invalid. 
19s A system error was encountered. 
The search string was not found. 


Notes on Using This Function 


e Search Presentation Space scans the host 
presentation space for the first occurrence of 
the specified string. 


— If the string is not located, then the 
Returning Length is set to 0. 


— Ifthe string is found, then the Returning 
Length is set to the string’s beginning 
location in the host presentation space. 
This location represents a position in the 
host presentation space based on the 
layout where the upper left corner (“row 1, 
column 1”) is location 1 and the bottom 
right location is 1920 for the Entry Level 
Emulation Program. 


e The Search Presentation Space function is 
useful in determining when the host 
presentation space is available. If your 
programmed operator is expecting a specific 
prompt or message before sending data, 
Search Presentation Space allows you to 
check for the prompt message before 
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continuing. If the expected prompt has not 
yet been sent, your program can call 
Function 18 Pause or Function 24 Query 
Host Update and continue to call Search 
Presentation Space until a zero return code 
is received. 


e Two sets of parameters under Function 9 Set 
Session Parameters relate directly to 
Search functions: 


Explanation 


SRCHALL Search will scan the entire host presentation space 


SRCHFROM Search will start from a specified beginning position. 


Parameter 
SRCHFRWD Search will be performed in an ascending direction. 


SRCHBKWD | Search will be performed in a descending direction. A 


Search will be satisfied if the first character of the requested 
string starts within the bounds specified for the Search. 


Search Presentation Space normally checks 
the entire host presentation space. However, 
you can use Function 9 to specify 
SRCHFROM. In this mode, you specify a 
starting position for the search operation. 
Then the function looks for the designated 
string from that starting position through the 
end of the host presentation space. This 
option is useful if you are looking for a 
keyword that may have multiple occurrences 
in the host presentation space. 


You can also use Function 9 to specify 


SRCHBKWD. Then the search operation 
locates the last occurrence of the string. 
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Send File (90) 


Send File is used to send a file from the PC 
session where EEHLLAPI is running to a host 
session. It is used the same way the “send” 
command js used in the Entry Level Emulation 
Program. However, the Send File function may 
be called by an EEHLLAPI application program. 


Parameters Required When Called 


Data String: The same send parameters as 
are usual for the Entry 
Emulator file transfer request. 


Length: Length of the target data string 
or EOT in the data string if in 
EOT mode. 

PS Position: Drive number 


The drive number indicates the location of the 


SEND.COM file where: 
Drive A = 1 
Drive B = 2 
Drive Z = 26 


If SEND.COM is located on a fixed disk, the file 
must be in the current subdirectory. 
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Values Returned 
You can receive three kinds of return codes: 
1. EEHLLAPI Return Codes 


If a problem was encountered with the way 
you specified your data string or with the 
system, you will receive one of these return 
codes: 


Return 
Code Explanation 
You have specified a data string length that is too long for the 
EEHLLAPI buffer. File transfer was unsuccessful. 
fo A system error was encountered. 


2. File Transfer Message Codes 


The message number of the Entry Level 
Emulation Program file transfer messages 
may be returned. For example, if you are 
using the Entry Level Emulation Program, 
file transfer message “TRANS003 File transfer 
complete” would send back a return code of 3. 
For a complete list of the file transfer 
messages, refer to Appendix A in the JBM PC 
8270 Emulation Program, Entry Level, User’s 
Guide. 


The most common messages you might receive 
are listed below: 


Return 
Code Explanation 
File transfer complete. 


File transfer complete with records segmented. 
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3. DOS Extended Error Codes 


The following DOS extended error codes are 
valid, preceded by the number “3” (added by 
EEHLLAPI). 


Return 
Code Explanation 
30 Invalid function number 


Access denied 


[aoe [File not found SSCS 
[906 | Access denied SCS 
[308 | tnwutficient memory SSCS 


Invalid format 


Notes on Using This Function 


1. You must not have issued a connect or 
reserve function call before using Send File. 
If you are linked to the host session already, 
you will receive File Transfer Message 7, 
“Cannot link to host: file transfer cancelled.” 


Therefore: 


e If you are connected (with Function 1 
Connect Presentation Space) to the host 
session, you must disconnect (using 
Function 2 Disconnect Presentation 


Space). 


e If you have reserved (with Function 11 
Reserve) a host session, you must release 
it (using Function 12 Release). 


2. Special considerations for providing a path 
back to COMMAND.COM exist when you use 


this function. 
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The parent application (EEHLLAPI) causes a 
subprocess program (like SEND.COM) to be 
loaded, and the subprocess program inherits 
the parent’s environment. The EEHLLAPI 
environment segment contains the path back 
to the COMMAND.COM used when 
EEHLLAPI was loaded. 


While some subprocess applications are 
running, COMMAND.COM may be overlaid 
and may have to be reloaded. Therefore, the 
COMMAND.COM must be available on the 
same path as EEHLLAPI. 


It also means that SEND.COM must be in the 
current directory when you issue a call to 
Function 90 Send File. This is not 
necessarily the root directory or the directory 
in use when EEHLLAPI was loaded, both of 
which may be changed by the time Send File 
function is executed. SEND.COM must be in 
the current directory. 


3. Two sets of parameters under Function 9 Set 
Session Parameters are related to this 


function: 
QUIET Keeps SEND and RECEIVE messages from being displayed. 


EEHLLAPI will keep track of the message number and 
discard the message. 


NOQUIET Restores the display of messages. 
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Explanation 


TIMEOUT=N | A one-character indicator from the table below will tell 
EEHLLAPI how many 30 second cycles (how many messages 
with trans010) it should accept before issuing a 
CTRL+ BREAK itself. 


Character Value Character Value 
(in (in 
minutes) minutes) 


5 


TIMEOUT=0 | Timeout messages will be displayed every 30 seconds until 
the operator presses CTRL+ BREAK (these messages would 
not be visible in the QUIET mode). This is standard for 
operator usage of SEND and RECEIVE. 


For additional information, see “Considerations 
for Using Functions 90 and 91” on page 3-44. 
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Send Key (8) 


Send Key sends a keystroke or a string of 
keystrokes to the host presentation space. Your 
EEHLLAPI application program must use 
Function 1 Connect Presentation Space before 
sending keystrokes. 


You define the string of keystrokes to be sent 
with the calling data string parameter. The 
keystrokes appear to the target session as though 
they were entered by the terminal operator. You 
can also send all attention identifier (AID) keys 
such as Enter, PA1, etc. All the fields that are 
protected for input or are numeric only must be 
treated accordingly. 


Parameters Required When Called 
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Data String: A string of keystrokes, 
maximum 255. 

Length: Length of the target data string 
or an EOT in the data string if 
in EOT mode. 

PS Position: NA 
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Values Returned 


el 
Code Explanation 


Input to the target session was inhibited or rejected; all of the 
keystrokes could not be sent. 


A system error was encountered. 


The host session was busy; all of the keystrokes could not be sent 


Notes on Using This Function 


The following guidelines may help you use the 
Send Key function more efficiently: 


e Keystrokes cannot be sent to a session whose 
keyboard is locked; for example, when input 
is inhibited. You can check this with 
Function 4, Wait. 


e Keystroke input is no longer accepted after 
the first AID character is received. The 
remainder of the input data string may be 
rejected if the host is busy. 


e To send special Control keys, a compound 
character coding scheme is used. This coding 
scheme uses two ASCII characters to indicate 
one keystroke and comprises the @ sign 
followed by the keycode. For example, to 
type in the sequence “LOGON ABCDE” 
followed by the Enter key, you would code 
the string “LOGON ABCDE@E.” A complete 
list of these keycodes is represented in 
“Keyboard Mnemonics” on page 3-63. 
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This compound coding technique allows an 
ASCII string representation of all necessary 
keystroke codes without requiring the use of 
complex hexadecimal key codes. The string 
length passed to the application should count 
these compound keystrokes as being 2 bytes 
long. 


You can specify an escape character other 
than “@” using Function 9 Set Session 
Parameters and specifying another 
character under “ESC = n.” 


The maximum length of a string that can be 
passed to the Send Key function in one 
request is 255 characters. However, your 
application program can make multiple calls 
to the Send Key function to transmit longer 
keystroke strings. 


Users needing higher performance should use 
Function 33 Copy String to Field or 
Function 15 Copy String to Presentation 
Space rather than send keystrokes with 
Function 3. 
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Keyboard Mnemonics 


This set of keyboard mnemonics is provided to 
allow you to use ASCII characters to represent 
the special function keys of the PC keyboard. A 
mnemonic abbreviation code makes these special 
keys easy to remember. An alphabetic key code 
has been used for the most common keys. For 
example, the Clear key is “C”, the Tab key is 
“T”, etc. Please note that the upper and lower 
case alphabetic characters are mnemonic 
abbreviations for different keys. 


@B Backtab @I Insert @T Tab 

@C Clear @L Cursor Left @U Cursor Up 
@D Delete @N New Line @V Cursor Down 
@E Enter @P Print @Z Cursor Right 
@F Erase EOF @R Reset 

@0 Home @7 PF7 @e PF14 @1 PF21 
@1 PF1 @8 PF8 @f PF15 @m PF22 
@2 PF2 @9 PF9 @g PF16 @n PF23 
@3 PF3 @a PF10 @h PF17 @o PF24 
@4 PF4 @b PF11 @i PF18 @x PA1 
@5 PF5 @ce PF12 @j PF19 @y PA2 
@6 PF6 @d PFi3 @k PF20 

@AG@C - Test @A@d - DOC Mode 


@A@D - Word Delete 
@A@E - Erase Input 
@A@H - System Request 
@A@I - Alt + Insert 
@AG@dJ - Cursor Select 
@AG@P - Ident 

@A@Q - Attention 
@A@R - Device Cancel 
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@AG@e - Wrap 

@A@f - Change Format 
@A@n - Cursor Position 
@S@x - Dup 

@S@y - Field Mark 
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AID Key Mnemonics 


The AID key mnemonics set by Function 3 Send 
Key are listed below: 


@1 PF1 @8 PF8 @f PF15 @m PF22 
@2 PF2 @9 PF9 @g PF16 @n PF23 
@3 PF3 @a PF10 @h PF17 @o PF24 
@4 P¥F4 @b PFi11 @i PF18 @x PA1 
@5 PF5 @c PF12 @j PF19 @y PA2 
@6 PF6 @d PF13 @k PF20 

@7 PF7 @e PF14 @1 PF21 

@AG@C - Test @C - Clear 

@A@H - System Request @E - Enter 

@A@3J - Cursor Select 

@A@Q - Attn 


You can specify an escape character other than 
“@” using an EOT delimiter defined using 
Function 9 Set Session Parameters and 
specifying another character under “ESC =n.” 


Note: The length of the data string is explicitly 
defined. You can also define the length 
implicitly using an end-of-transmission 
(EOT) delimiter using Function 9 Set 
Session Parameters. 
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Set Session Parameters (9) 


Set Session Parameters lets you change 
certain default session options in EEHLLAPI, 
the resident interface module. 


Parameters Required When Called 


Data String: String containing the session 
parameters.* 

Length: Explicit length of the data 
string (KOT mode is not 
allowed). 


PS Position: NA 


*The Calling Data String can contain any of the 
parameters below. The parameters should be 
placed on the Calling Data String line, separated 
by commas or blanks. The sets of parameters are 
explained in terms of the functions they affect. 
The default is underlined. 


The next three sets of parameters affect Copy 
functions. The parameter EOT =n also affects 
Functions 90 (Send File) and 91 (Receive File): 


Explanation 


ATTRB Pass back all codes that do not have an ASCII equivalent as 
their original values. 


NOATTRB Convert all unknown values to blanks. 


STRLEN An explicit length will be aed for all strings. 


STREOT String lengths are not explicitly coded. They are terminated 
with an EOT (End of Text) character. 
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Explanation 


EOT=n Allows you to specify the EOT character for string 
terminators (in STREOT mode). Binary zero is the default. 
Do not leave a blank after the equals sign. 
The next two sets of parameters affect Function 3 
Send Key: 


Parameter Explanation 


ESC=n Specify the escape character for keystroke mnemonics (@ is 


the default). Do not leave a blank after the equals sign. 
Blank is not a valid character. 


AUTORESET | The application will attempt to reset all inhibited conditions 
by prefixing all strings of keys sent using Function 3 Send 
Key with a reset. 


NORESET Do not AUTORESET. 


The next two sets of parameters affect Search 
functions: 


Parameter 
SRCHALL Search will scan the entire host presentation space. 
SRCHFROM Search will start from a specified beginning position. 


SRCHFRWD Search will be performed in an ascending direction. 


SRCHBKWD | Search will be performed in a descending direction. A 
search will be satisfied if the first character of the requested 
string starts within the bounds specified for the search. 
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The next set of parameters relates to using 
TRACE to debug your EEHLLAPI program. 
Refer to “Using Trace to Help You Debug Your 
Program” on page 4-16 for more information 
about this parameter. 


Explanation 
TRON 


Turns trace off. 


The trace function may conflict with messages on the screen 
from languages or applications that manage their own 

displays. For more information about Trace messages, refer 
to Appendix A, “EEHLLAPI Messages.” 


The next set of parameters affects Function 4 
Wait: 


Explanation 


TWAIT Wait will wait up to a minute before timing out on 
XCLOCK or XSYSTEM. 


LWAIT Wait will wait until XCLOCK/XSYSTEM clears. This 
option is not recommended since contro! does not return to 
your application until the host is available. 


Wait checks status and returns immediately (no wait). 


Two parameters under Function 9 affect 
Disconnect: 


Parameter Explanation 


CONPHYS During the Connect, jump to the requested presentation 
space (Do a physical connect). 
CONLOG 


During the Disconnect, jump to the PC session where the 
EEHLLAPI application is running (Do a physical 
disconnect). 


During the Connect, do not jump to the requested 
presentation space (Do a logical connect). 


During the Disconnect, do not jump to the PC session. Stay 
at the current presentation space — could be at the HOST or 
PC (Do a logical disconnect). 
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This set of parameters affects Function 18 Pause: 


Explanation 


FPAUSE If full-duration pause, it will pause for however long you 
specified in Set Session Parameters. 


IPAUSE Interruptible pause. Function 23 Start Host Notification 
and a host event will satisfy a Pause. 


The two next sets of parameters affect Function 
90 Send and Function 91 Receive: 


Explanation 


QUIET Keeps SEND and RECEIVE messages from being displayed. 
EEHLLAPI will keep track of the message number and 
discard the message. 


NOQUIET Restores the display of messages. 


Parameter Explanation 


TIMEOUT=N | A one-character indicator from the table below will tell 
EEHLLAPI how many 30 second cycles (how many messages 
with TRANSO10) it should accept before issuing a 

CTRL+ BREAK itself. 


Character Value Character Value 
(in (in 


minutes) minutes) 


Timeout messages will be displayed every 30 seconds until 
the operator presses CTRL + BREAK (these messages would 
not be visible in the QUIET mode). This is standard for 

operator usage of SEND and RECEIVE. 


TIMEQUT=0 
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Values Returned 


|0 | The session parametershavebeen set. 
[2 _| The length ofthe parameter listisinvalid, 
fo Aayotom err was encountered SSC*d 
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Start Host Notification (23) 


The Start Host Notification function begins the 
process by which your EEHLLAPI application 
program determines if the host PS/OIA have been 
updated. This version of EEHLLAPI does not 
distinguish between PS and OIA updates. 


After using this function, your application 
program can use Function 24 Query Host 
Update to determine what specific host event 
has occurred. 


Parameters Required When Called 


Data String: Preallocated string. See Note 
below. 

Length: The length of the host event 
buffer (256 recommended). 

PS Position: NA 


Note: The Calling Data String contains these 
elements: 


One of the following: 


@ A specific host presentation space short name (PSID) 
@ =A blank or null indicating a request against the host 


Position 1 
presentation space 


Position 2 The character B asking for notification of both host 
presentation space and OIA updates ; 


Positions 3-6 The 4-byte address of a preallocated buffer space to be 
used internally for enqueuing and dequeuing of host 
*Internally, this address is represented as a 


events. The suggested size of this space is 256 bytes, 
specified in the calling “Length” parameter.* 

2-byte offset followed by a 2-byte segment address 

of the buffer. 
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All supported languages may use Function 17 
Storage Manager Subfunction 1 Get Storage 
to obtain a buffer block of storage. Get Storage 
allows all languages to get additional storage 
and to free smaller blocks of storage as needed. 


Function 17 Storage Manager Subfunction 1 
Get Storage returns a 4-byte address in the 
“Data String” parameter that can be 
concatenated with the first data string bytes for 
this function. 


The following restrictions exist for individual 
languages: 


e PASCAL or C: You choose either to use the 
Storage Manager function to provide the 
address of the buffer or to provide your own 
address pointer capability to point to a buffer 
structure in your data area. 


e Interpretive or Compiled BASIC: You must 
use the Storage Manager function since 
BASIC variables do not remain in a fixed 
location. 


e COBOL: You may use the Storage Manager 
function to provide the needed 4-byte address. 
Otherwise, your EEHLLAPI program must fill 
the space with 4 bytes of binary zeros (low 
value) so that the COBOL LIM will know 
that the buffer following immediately after 
the 4 bytes of binary zeros is a continuing 
part of that data structure. In this case, the 
COBOL LIM will provide the address itself 
for a common EEHLLAPI interface. 


Note: If you allocate buffer storage with any 
language within your LEHLLAPI program 
(rather than using Function 17 Storage 
Manager), you must call Function 25 
Stop Host Notification before you exit 
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EEHLLAPI. (You could also use Function 
21 Reset System to accomplish the same 
purpose). Failure to do so may cause 
subsequent programs to fail 
unpredictably with storage overlays. 


Values Returned 


lee 
Code Definition 

0 __| Start Host Notification was success. —————S—S~S 
[2_| An error was made in designating parameters. ~~ 
[2 _[A system error was encountered. SSCSC~S 


Notes on Using This Function 
In order to use this function, Storage Manager 


can be utilized. A Get Storage call should be 
made. See “Storage Manager (17)” on page 3-74. 
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Stop Host Notification (25) 


The Stop Host Notification function disables 
the capability of Function 24 Query Host 
Update to determine if the host PS/OIA have 
been updated. This function also stops host 
events from affecting the Pause function. 


Parameters Required When Called 


Data String: One-character short name of the 
target presentation space ID. 
Length: NA (implied length of 1 byte). 


PS Position: NA 


Values Returned 


Stop Host Notification was successful 


1 An invalid host presentation space was specified, one labeled with 
an invalid name. 


No previous Start Host Notification was issued. 
A system error was encountered. 


Notes on Using This Function 


After issuing Stop Host Notification, the 
Storage Manager subfunctions “Free Storage” 
or “Free All Storage” should be utilized if a 
previous “Get Storage” call was issued during 
Start Host Notification. See “Storage Manager 
(17)” on page 3-74. 
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Storage Manager (17) 


The Storage Manager function is used in 
EEHLLAPI to allocate or deallocate queue 
storage for Function 23 (Start Host 
Notification). 


The Storage Manager function solves a storage 
allocation problem created by BASIC, but can be 
used with KEEHLLAPI application programs 
written in other supported languages as well. 


Users of BASIC can use Storage Manager to 
overcome the problem of dynamic storage pools 
used by BASIC. 


The following restrictions exist for individual 
languages: 


e PASCAL or C: You choose either to use the 
Storage Manager function to provide the 
address of the buffer or to provide your own 
address pointer capability to point to a buffer 
structure in your data area. 


e Interpretive or Compiled BASIC: You must 
use the Storage Manager function since 
BASIC variables do not remain in a fixed 
location. 
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e COBOL: You may use the Storage Manager 
function to provide the needed 4-byte address. 
Otherwise, your EEHLLAPI program must fill 
the space with 4 bytes of binary zeros (low 
value) so that the COBOL LIM will know 
that the buffer following immediately after 
the 4 bytes of binary zeros is a continuing 
part of that data structure. In this case, the 
COBOL LIM will provide the address itself 
for a common EEHLLAPI interface. 


Note: If you allocate buffer storage with any 
language within your EEHLLAPI program 
(rather than using Function 17 Storage 
Manager), you must call Function 25 
Stop Host Notification before you exit 
EEHLLAPI. (You could also use Function 
21 Reset System to accomplish the same 
purpose.) Failure to do so may cause 
subsequent programs to fail 
unpredictably with storage overlays. 


The preferred way to allocate storage for use by 
EEHLLAPI functions is to use the Storage 
Manager function. Three calls can be made to 
Storage Manager: 


e Get Storage 
e Free Storage 
e Free All Storage. 


Since each of these subfunctions has its own 
calling and returning parameters and generates 
its own set of return codes, each will be 
discussed as an individual subfunction. These 
subfunctions are identified to EEHLLAPI by 
passing the subfunction number in the calling 
“PS Position” parameter. 
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Get Storage 


Get Storage allocates a piece of the storage 
block to be used by an application as a queue 
structure for Start Host Notification. 


Parameters Required When Called 


Data String: NA (preallocated to 4 bytes). 
Length: Size (in bytes) of the requested 
storage area. 

PS Position: 01 (for Get Storage). 


Values Returned 


The subfunction returns three pieces of 
information: 


e The Data String contains the storage address 
expressed as two binary words in offset 
segment order. This string should be used in 
Positions 3-6 in the Data String defined for 
Start Host Notification. 


e The Length parameter contains the storage 
block ID. 
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e The Return Code, which is one of the 
following: 


Return 
Code Explanation 
The requested storage was allocated. 
You have requested more storage than is available. 


2 The LIM to which your EEHLLAPI application program is linked 
does not support this function. 


A system error was encountered. 


Storage Manager is not available. 


Notes on Using This Function 


For EEHLLAPI the Storage Manager function 
is designed to simulate the full functions 
provided on the 3270 PC HLLAPI. Warning: 
Users should ONLY use this function to 
allocate storage for Function 23, Start Host 
Notification. If you attempt to use the 
allocated storage for other purposes, the 
results are unpredictable. 
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Free Storage 


Free Storage frees the block of storage 
allocated by Subfunction 1 Get Storage. This 
function should be used after to a Stop Host 
Notification request in order to free “queue” 
memory created by a Get Storage call on Start 
Host Notification. 


Parameters Required When Called 


Data String: NA (preallocated to 4 bytes). 

Length: ID of the storage block to be 
freed. 

PS Position: 02 (for Free Storage). 


Values Returned 


The subfunction returns these return codes: 


Return 
Code Explanation 


ae The storage has been freed. 
2 The storage block ID was invalid, or the LIM to which your 
EEHLLAPI application program is linked does not support this 
function. 


A system error was encountered. 
Storage Manager is not available. 


Once a block of storage has been allocated, the 
block remains the size of the original allocation. 
A subsequent request for storage will waste the 
excess storage in the previously allocated block. 
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Free All Storage 


Free All Storage frees all allocated storage 
blocks. The storage blocks are regrouped into a 
single storage pool that is the same size as the 
original block of memory allocated. 


Parameters Required When Called 


Data String: NA (preallocated to 4 bytes) 
Length: NA 
PS Position: 04 (for Free All Storage) 


Values Returned 


The size of the largest available block of storage 
is returned in the “Length” parameter. 


One of the following return codes is also 
returned: 


Return 
Code Explanation 
Cae Free All Storage was successful. 
The LIM to which your EEHLLAPI application program is linked 
does not support this function. 
ig A system error was encountered. 
Storage Manager is not available. 
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Wait (4) 


Wait checks the status of the host presentation 
space. If the session is waiting on a host response 
(indicated by XCLOCK or XSYSTEM), the Wait 
function will cause EEHLLAPI to wait up to one 
minute to see if the condition clears. 
Parameters Required When Called 
Data String: NA 
Length: NA 


PS Position: NA 


Values Returned 


The following return codes are valid: 


Return 
Code Definition 


[0 ___| The keyboard is unlocked and ready for tapas SSS 
is locked. 


|4 __{ Timeout while still in XCLOCK or XSYSTEM 
The keyboard is locked 
fo __[Assyotem error was encountered. ———SSCSC~SCS 
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Notes on Using This Function 


Wait is used to give host requests like those 
made by Function 3 Send Key the time required 
to be completed. Using Function 9 Set Session 
Parameters, you can make the request in three 
ways: 


Explanation 


Wait will wait up to a minute before timing out on 
XCLOCK or XSYSTEM. 


Wait will wait until XCLOCK/XSYSTEM clears. 


Note: This option is not recommended since control does not 
return to your application until the host is available. 


NWAIT Wait checks status and returns immediately (no wait). 


You can use this function to see if the host OIA 
is inhibited. 


Wait is satisfied by the host unlocking the 
keyboard. This may not mean the transaction 
has been completed, so you should use Search 
combined with Wait to look for expected 
keyword prompts. 
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Chapter 4. Compiling and 
Running Your EEHLLAPI 
Application Program 


You learned in Chapter 1 that when you have 
finished writing your EEHLLAPI application 
program, you can make the corresponding 
Language Interface Module (LIM) a permanent 
part of your program. This chapter teaches you: 


e How to link your EEHLLAPI application 
program with the appropriate LIM 


e How to run your application program 


e How to use Trace to help you debug your 
program. 


Linking Your EEHLLAPI 
Application Program with the 
Appropriate LIM 


When you are ready to run your EEHLLAPI 
application program, you can make the 
appropriate LIM a permanent part of your 
program in this manner: 


e If you are using a compiled language (such as 
COBOL or Compiled BASIC), you call the 
appropriate language interface as an external 
subroutine. When you link-edit your program 
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(using the DOS link command), the 
appropriate LIM will be merged with your 
EEHLLAPI program. 


e If you are using the Interpretive BASIC 
language, you will have to use another 
technique for calling the BASIC LIM 
(Interpretive BASIC has no provision for 
using the DOS link command to include an 
external subroutine). Instead, you must access 
a special Interpretive BASIC LIM that is 
available whenever EEHLLAPI is loaded. 


Each language that you can use to call 
EEHLLAPI functions has its own programming 
conventions and requirements. These 
requirement are explained below for the 
languages supported directly by EEHLLAPI 
(those for which LIMs are provided). For 
information about writing a LIM to support 
another programming language, refer to 
Appendix B, “Writing Your Own Language 
Interface Module.” 


Information about each directly supported 
high-level language follows. 


4-2. Programming Guide 


Using BASIC 


Using BASIC 


The EEHLLAPI Function 5 Copy Presentation 
Space is not available to application programs 
written in Interpretive BASIC. Users of BASIC 
have a choice of two programming environments: 
Interpretive BASIC and Compiled BASIC. While 
these environments are similar, differences exist 
in subroutine linkage and string handling. 


Interpretive BASIC 


If you use Interpretive BASIC, you will need 
special initialization programming to access the 
Interpretive BASIC language interface that is in 
the EEHLLAPI module. The special code locates 
the interface from a fixed pointer location and 
uses this address to set the SEG and OFFSET 
values for the subroutine call. 


If you don’t understand the routine involved, 
don’t worry; just copy the following program 
statements into your program’s initialization 
routine: 


DEF SEG = 0: APILOC=PEEK(&H1FE) + PEEK(&HI1FF) 


IF APILOC = 0 THEN PRINT “EEHLLAPI IS NOT AVAILABLE”: END 
DATA &HO4B8, &HB301, &HCDBB, &HCA7F, &HO002 

DIM APICALL% (4) 

FOR I=0 to 4: READ APICALL%(I): NEXT I 

BLIMSET = VARPTR (APICALL%(0) ) 

DEF SEG: CALL BLIMSET (APICALL%(1) ) 

BLIM=APICALL%(1): DEF SEG = APICALL%(0) 


IF BLIM = &HB301 THEN PRINT “EEHLLAPI NOT AVAILABLE’: END 


Note: While the initialization code used by 
Interpretive BASIC is not required by 
Compiled BASIC, it is compatible with it, 
allowing you to develop a program with 
Interpretive BASIC and then to compile it 
to improve performance. 
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To call the interface from BASIC, you use a fixed 
format call with fourparameters. These 
parameters must occur in a fixed sequence and 
all four parameters must be in the call list, even 
if they aren’t used. If a parameter isn’t needed 
for a given call, you don’t need to value it. 


The call format is: 


100 CALL BLIM (FUNC%,SDATAS , DLEN%, RETC%) 


Where: 


FUNC% is the function code 
SDATAS$ is a string of data 
DLEN% is the data length 
RETC% is the return code. 


Please note these restrictions in defining these 
parameters; 


e The parameters can have any names, but they 
must be of the proper type. Refer to the 
definitions of the calling parameters under 
“Parameters Required When Called” on 
page 3-1 and of the returned parameters 
under “Values Returned” on page 3-2. 


e The function code, data length, and return 
code must be two-byte integer variables. 


e The data string must be a string variable. 


Users of BASIC need to carefully review the 
restrictions for string processing. 


e Since the maximum string length for 
Interpretive BASIC is 255 bytes, Function 5 
Copy Presentation Space is not available, 
but Function 8 Copy Presentation Space to 
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String may be used to extract segments of the 
host presentation space. 


e String variables are managed dynamically in 
BASIC’s data segment. This means that all 
strings must be preallocated before they can 
receive data from the interface. 


While this may sound complicated, all it means is 
that the subroutine package cannot change the 
size of a string, so you must preformat your 
string to the required size. 


Let’s look at an example: 


1000 SDATAS=SPACES$(80) 'PREALLOCATE TO 80 BYTES 

1010 FUNC%=08 'COPYSTRING FUNCTION 

1020 DLEN%=80 ‘COPY 80 BYTES 

1030 RETC%=1 ‘LOCATIONS 1-80 FOR COPY 

1035 REM NOTE USE OF RETC% TO PASS OFFSET FOR COPYSTRING 
1040 CALL BLIM(FUNC3,SDATAS,DLEN%,RETC%) 


If you forget to preallocate your strings, the 
BASIC LIM attempts to detect this condition and 
will return a parameter specification error. 


An issue related to string preallocation for 
Interpretive BASIC is string performance. If you 
are writing complex or long-running 
applications, you should understand the 
implications of Interpretive BASIC’s string usage 
so that you can take steps to avoid degraded 
performance. 


Interpretive BASIC manages strings dynamically. 
This means that as you assign and reassign data 
to a string, Interpretive BASIC reacquires space 
in its dynamic storage pool. 


While this is not a problem for many programs, if 
you write a complex application that uses strings 
frequently, Interpretive BASIC may continue to 
append strings. This can result in lengthy 
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pauses in your program’s execution while BASIC 
compresses strings. 


Compiled BASIC 


Users of Compiled BASIC can call the Compiled 
BASIC Language Interface Module (BLIM) as an 
external call. In order to do this, use the link 
module provided with Compiled BASIC to link 
the Compiled BASIC LIM (named 
HLLCBAS.OBJ and located on your Entry 
Emulator diskette) with your EEHLLAPI 
application program. To do this, follow these 
general instructions: 


1. Compile your EEHLLAPI program as 
instructed in the IBM Compiled BASIC 
manual. 


2. Place your IBM BASIC Compiler “BASIC” 
diskette containing the file LINK.EXE in 
your default diskette drive. 


3. Have your compiled EEHLLAPI program and 
the file HLLCBAS.OBJ from your Entry 
Emulator diskette available. You will need to 
specify the drive locations of these programs 
for the link program and add path 
information to the basic link command 
provided below. 


4. Type LINK YOURPROG + HLLCBAS; after 
the DOS prompt. 


This will produce an executable module named 
YOURPROG.EXE. After loading EEHLLAPI, 
you can execute the BASIC program in the usual 
manner. 
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For more details about linking programs under 
Compiled BASIC, refer to IBM Personal 
Computer Language Series: BASIC Compiler. 


For programming samples in BASIC, refer to the 
individual functions and the BASIC program 
sampler. 
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Using COBOL 


If your are writing your EEHLLAPI program in 
COBOL, be aware that the COBOL program 
should declare the parameter variables in the 
Data Division. 


Here is an example of the parameter declaration: 


77 FUNCODE PIC 99 COMP-0. 
77 -‘RETCODE PIC 99 COMP-0. 
77 STRLEN PIC 99 COMP-(;. 
O01 DATA-STRING PIC X(1920) VALUE SPACES. 


You have the option of changing the data names 
to fit your own programming conventions. The 
string variable should always be large enough to 
receive the largest amount of host data you will 
request. 


The call to the COBOL LIM would be coded: 


CALL 'HLLCOB' USING FUNCODE DATA-STRING STRLEN RETCODE. 


Once you have compiled your EEHLLAPI 
program, you will need to use the DOS link 
command to link it with the COBOL LIM (named 
HLLCOB.OBJ on your Entry Emulator diskette). 


To do this, follow these general instructions: 


1. Compile your EEHLLAPI program as 
instructed in the IBM Personal Computer 
Language Series: COBOL manual. 


2. Place your DOS “Supplemental Programs” 
diskette in your default diskette drive. 


3. Have your compiled EEHLLAPI program and 
the file HLLCOB.OBJ from your Entry 
Emulator diskette available. You will need to 
specify the drive locations of these programs 
for the link program and add path 
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information to the basic link command 
provided below. 


4. Type LINK YOURPROG + HLLCOB; after 
the DOS prompt. 


This will produce an executable module called 
YOURPROG.EXE. After loading EEHLLAPI 
you may execute this COBOL program in the 
normal manner. 


For more details about linking programs under 
DOS, refer to the IBM Personal Computer 
Language Series: Disk Operating System manual. 
For more details about using COBOL, refer to 
IBM Personal Computer Language Series: 
COBOL. 
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Using PASCAL 


If you are writing your KEHLLAPI program in 
PASCAL, you should note that PASCAL needs to 
declare the required variables and to link to the 
PASCAL language interface module. The 
following is an example of the necessary 


definitions: 
VAR 
FUNC, (* Function number *) 
LEN, (* Length of the data string *) 
RETC : INTEGER; (* EEHLLAPI return code *) 


, 
CONN. PS.STR: STRING(1); 
(* Connect Presentation Space string*) 


PROCEDURE HLLPAS (VAR LIM_FUNC: INTEGER; 
VAR LIM_STR: STRING; 
VAR LIM_LEN, 
1IM_RETC: INTEGER); EXTERN; 


The call to the LIM would then be coded: 


HLLPAS (FUNC,CONN_PS _STR,LEN,RETC) ; 


Several EEHLLAPI functions separate the data 
string, either on call or return, into a series of 

fields. Although IBM PASCAL 2.0 provides no 
explicit substringing functions for variables of 

type STRING, there are ways to work with the 

fields within the data string. 


One suggested method is to use record overlays. 
By setting the address of a record equal to the 
address of the data string, you can directly 
access the different type fields within the data 
string. For example, a call to Function 20 Query 
System can be done as shown on the following 
page. 


4-10 Programming Guide 


Using PASCAL 


PROGRAM QSYS(INPUT,OUTPUT) ; 


TYPE 
(* Query System overlay type 
(* [xx] necessary for proper 
QSYSOVLTYP = RECORD (* byte alignment 


HLLVERS [00]: STRING(1); (* EEHLLAPI version number 
HLLLVL [01]: STRING(2); (* EEHLLAPI level number 
HLLDATE [03]: STRING(6); (* EEHLLAPI date 
LIMVERS [09]: STRING(1); (* LIM version number 
LIMLVL {10}: STRING(2); (* LIM level number 
HARDW [12]: STRING(1); (* Hardware base 
CPTYPE [13]: STRING(1); (* Control Program type 
CPLVL [14]: STRING(1); (* Control Program level 
RES1 [15]: STRING(1); (* Reserved 
RES2 [16]: STRING(2); (* Reserved 
PCSHRTN [18]: STRING(1); (* PC session short name 
COMPRC [19]: STRING(4); (* Component error return code 
SYSRC {23]: STRING(4); (* System error return code 
RES3 [27]: STRING(9); (* Reserved 
END; 
VAR 
FUNC, (* Function number 
LEN, (* Length of the data string 
RETC : INTEGER; (* EEHLLAPI return code 


QuSYSLOVL: QSYSOVLTYP; 

(* Query System Overlay 
Q.SYS_STR: STRING(35); 

(* Query System data string 
QUSYS_PTR: ADS OF QUSYS_OVL; 

(*pointer to the Q System overlay*) 


PROCEDURE HLLPAS (VAR LIM_FUNC: INTEGER; 
VAR LIM_STR: STRING; 
VAR LIM_LEN, 
LIM_RETC: INTEGER); EXTERN; 


BEGIN 
(* ee a a a we a ew a a wr we er we re ee ee ee ee 
(* Query System (Function 20) 
(* Soe ee nee Ce me me me ms ems meme ane SOS me ane cs eee ee es se es ee eee oo oe ee 
FUNC := 20; 
LEN := 35; (* Data String Length 
RETC := 0; 


HLLPAS (FUNC,QUSYS_STR,LEN,RETC) ; 


Q.SYS_PTR := ADS OF Q_SYS_STR; 


*) 


(* Set overlay on string*) 


WITH QO_LSYS_PTR DO 
BEGIN 
WRITELN('EEHLLAPI version number: 
WRITELN('EEHLLAPI level number: 
WRITELN('EEHLLAPI date: :23, HLLDATE 
WRITELN('LIM version number: :23, LIMVERS 


':23, HLLVERS 
t 
t 
' 
WRITELN('LIM level number: ':23, LIMLVL 
' 
' 
' 
' 


:23, HLLLVL 


me Ne Se Ne we we te te 


WRITELN('Hardware base: :23, HARDW 
WRITELN('Control Program type: 2:23, CPTYPE 
WRITELN('Control Program level: 223, CPLVL 


WRITELN('Base PC short name 7:23, PCSHRTIN) ; 


WRITELN('Component return code: ':23, COMPRC ); 
WRITELN('System return code: ':23, SYSRC_ ) 
END; 


END. 
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Once you have compiled your EEHLLAPI 
program, you will need to use the DOS link 
command to link it with the PASCAL LIM 
(named HLLPAS.OBJ on your Entry Emulator 
diskette). 


To do this, follow these general instructions: 


1. Compile your EEHLLAPI program as 
instructed in the IBM Personal Computer 
Language Series: PASCAL manual. 


2. Place your DOS “Supplemental Programs” 
diskette in your default diskette drive. 


3. Have your compiled EEHLLAPI program and 
the file HLLPAS.OBJ from your Entry 
Emulator diskette available. You will need to 
specify the drive locations of these programs 
for the link program and add path 
information to the basic link command 
provided below. 


4. Type LINK YOURPROG+HLLPAS; after 
the DOS prompt. 


This will produce an executable module called 
YOURPROG.EXE. After loading EEHLLAPI 
you may execute this PASCAL program. 


For more details about linking programs under 
DOS, refer to the IBM Personal Computer 
Language Series: Disk Operating System manual. 
For more details about using PASCAL, refer to 
IBM Personal Computer Language Series: 
PASCAL. 
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Using IBM C 


If you are writing your KEHLLAPI program in 
IBM C, you should note that IBM C needs to 
declare the required variables and to link to the 
IBM C language interface module. The following 
is an example of the necessary definitions: 

INT API_FUNC, API _LEN, 


API_RETC 
CHAR API_STRING [255] 


The call to the language interface would then be 
coded: 


HLLC(&API_FUNC, API _STR, &API_LEN, SAPI_RETC); 


Once you have compiled your EEHLLAPI 
program, you will need to use the IBM C CLINK 
command to link it with one of three IBM C 
LIMS, depending on the memory model option 
specified during compilation 


e HLLC _S.OBJ (small memory model) 

e HLLC _M.OBJ (medium memory model) 
e HLLC _L.OBJ (large memory model). 

To do this, follow these general instructions. 


1. Compile your EEHLLAPI program as 
instructed in the IBM Personal Computer 
Language Series: C Compiler Compile, Link 
and Run manual. 


2. Have your compiled EEHLLAPI program and 
the file “HLLC_X.OBJ” (where “X” is either 
S, M, or L, depending on memory model 
option selected) from your Entry Emulator 
diskette available. You will need to specify 
the drive locations of these programs for the 
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link program and add path information to the 
basic link command provided below. 


3. Type CLINK YOURPROG+HLLC _X; after 
the DOS prompt. 


This will produce an executable module called 
YOURPROG.EXE. After loading KEEHLLAPI, 
you may execute this IBM C program. 


For more details about compiling and linking 
programs under DOS, refer to the IBM Personal 
Computer Language Series: C Compiler Compile, 
Link and Run manual. 


Using 8088 Assembler 


If you program in the Assembler language, you 
do not need a LIM. You can use software 
interrupts instead. If you are using an 
EEHLLAPI program written under this version 
of EEHLLAPI, you can invoke EEHBLAPI.EXE 
directly by issuing an Interrupt hex 7F with 
AH=01, AL=04, and BX =00. 


At the time of the interrupt, DS:SI should point 
to a Parameter Control Block specifying your 
parameters. For more detail on how to construct 
a parameter control block for Assembler 
language, see Appendix B, “Writing Your Own 
Language Interface Module.” 
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Running Your EEHLLAPI 
Application Program 


When you are ready to run your KEHLLAPI 
program with an application, your EEHLLAPI 
program should have the following available: 


1. Have your Entry Level Emulation Program 
and EEHLLAPI loaded into storage. 


2. Besure that any DOS files you plan to use 
are available to your EEHLLAPI program as 
specified by the individual functions. This 
includes the Entry Emulation utilities, such 
as 


e SEND.COM 
e RECEIVE.COM. 
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Using Trace to Help You Debug 
Your Program 


If you need help tracing program events when 
you are debugging your EEHLLAPI application 
program, you might want to turn on Trace using 
Function 9 Set Session Parameters. The TRON 
and TROFF parameters are explained below. 


TRON 
TROFF 


By turning Trace on, EEHLLAPI will indicate: 


e When a function begins execution 
e When the function completes 
e What return code was returned. 


The Trace function may conflict with messages 
on the screen from languages or applications 
that manage their own displays. For more 
information about Trace messages, refer to 
Appendix A, “EEHLLAPI Messages.” 
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Appendix A. EKEHLLAPI 
Messages 


Messages from the Personal Computer 
High-Level Language Application Program 
Interface can be identified by the prefix “KHL” 
and a message code followed by the message text. 
The message codes have the following format: 


e EHLnnn ‘Message Text’ 

Where ‘nnn’ is a message ID. 

The messages are listed below in numerical 
order: 


EHLO01 EEHLLAPI is loaded 


Explanation: The program is now loaded. 
This message is followed by EHL002. 


EHL002 EEHLLAPI is ready for use 


Explanation: The program is successfully 
loaded and available for your use. This 
message is displayed after EHLOO1 or 
EHLO003. 


EHL003 EEHLLAPI is already loaded 
Explanation: You entered the command 
eehllapi when the EEHLLAPI program was 
already loaded. This message is followed by 
EHL002. 


Since you have already loaded EEHLLAPI, 
the program is available for use. 
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EHL004 


EHL005 


EHL008 


EHLO10 


Unable to load EEHLLAPI 


Explanation: After you entered the 
command eehllapi, an error occurred while 
trying to load the program. The message 
that was displayed before this one indicates 
what went wrong. The program is not 
available for use. 


Incorrect level of the Entry Level 
Emulation Program. 


Explanation: You have loaded an incorrect 
level of the Entry Level Emulation Program. 
This message is followed by EHL004. The 
program is not available for use. 


System error - 88nn 


Explanation: An error with the Entry 
Level Emulation Program was encountered 
while trying to load EEHLLAPI. This 
message is followed by EHL004. The program 
is not available for use. 


“88nn” is a four-digit return code. The first 
two digits are always “88” to indicate 
EEHLLAPI. Record this information and 
have it available when you talk with your 
service coordinator. 


EEHLLAPI trace. Request nn 


Explanation: You specified TRON 

(Trace On) as a session parameter. This 
message indicates which request you have 
invoked. “nn” is the request number in 
hexadecimal notation. The trace messages 
may conflict (overlap) with your application 
messages if you are using a language like 
BASIC that manages its own display. 
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EHLO12 EEHLLAPI trace. Return code: nnnn 


Explanation: You specified TRON 

(Trace On) as a session parameter. This 
message indicates ending status for each 
request. These return codes are dependent 
upon the EEHLLAPI request that was 
executed. Note that this may overlap with 
messages from programs that track their 
own screen management (i.e., BASIC). The 
value is displayed in hexadecimal notation. 
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Appendix B. Writing Your Own 
Language Interface Module 


The Personal Computer High-Level Language Application 
Program Interface is designed to allow you to develop 
support for languages and features that may be unique to 
your environment. By using a language interface module 
(LIM) as a bridge between the application program and 
the primary interface program, you can: 


e Write a LIM for any language you may wish to 
support. 


e Use an existing LIM as a gateway to other external 
functions. 


e Change the format of the function calls or parameter 
lists to better suit your environment. 


The most basic step in getting ready to write your own 
LIM is to understand how the parts of EEHLLAPI work 
together. Refer to Figure B-1 on page B-3 as you read this 
information. 
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Writing Your Own LIM 


Let’s look at a typical example of how your EEHLLAPI 
application program uses a EEHLLAPI function. 


1. Your EEHLLAPI program calls the appropriate LIM. 


2. The LIM takes your program’s parameters and builds a 
parameter control block. 


3. The LIM passes this control block and your 
EEHLLAPI request to the resident interface module 
(EEHLLAPI.EXE) by means of software interrupt hex 
7F. 


4. EEHLLAPI interprets the information and passes the 
request on to the Entry Level Emulation Program. 


5. The Entry Level Emulation Program performs (or 
attempts) the task. 


6. After the task is completed (or attempted), EEHLLAPI 
places a return code in the parameter control block 
and returns control to the calling LIM. 


7. The LIM then returns control to your KEHLLAPI 
application program. 


B-2 Programming Guide 


Appendix B 


The path looks something like this: 


Entry Level Emulation Program 
co Task is Performed 


Interprets the Call And EEHLLAPI. EXE 
and Passes Is Informed 
Request to... | 


Resident Interface Module 
(EEHLLAPI EXE) 


Software Interupt hex 7F f@ Fills PCB 


PCB contains 
Return Code 
and Result 
Code 


Parameter 
Control 
Block (PCB) 


And Returns 
Control To... 


Language Interface Module 
(LIM) 


LIM Builds... 


Returns Control 
Call a EEHLLAPI Pee 


Function 


Your EEHLLAPI Application Program 
(Running with DOS) 


Figure B-1. The Parts of EEHLLAPI 
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Writing Your Own LIM 


Functions a LIM Can Perform 


The primary functions of a LIM are as follows: 

e Handle linkage from the calling application. 

e Obtain data parameter pointers or values. 

e Convert any language-unique data formats. 

e Construct a control block for the primary program. 
e Call (using an interrupt) EEHLLAPI.EXE. 

e Receive control back from EEHLLAPI.EXE. 


e Pass back necessary parameters and return control to 
the calling application. 


If you are writing support for a language, you only need 
the above functions. If you want to extend these 
functions, there are two primary areas for interface 
extension: 


1. Support for additional external functions 


2. Modification or extensions of user calls to the primary 
program. 


Frequently, users of Personal Computer languages develop 
multiple subroutine packages to provide utility functions 
such as display managers and data managers. Many of 
these packages require the application developers to call 
external subroutines. If you would like to consolidate 
several of your subroutines into one function package, 
you may write an extended LIM for this purpose. 
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Two different techniques are available: 


1. The simpler technique is to reserve a range of function 
codes for each subroutine package. The LIM then 
examines the function code being invoked and calls 
the appropriate subroutine package. You may need to 
make adjustments in the number and type of 
parameters passed to EEHLLAPI. 


2. A second technique for interface extensions is more 
complex. Function Code 0 has been reserved for a 
Signal Gateway function. In this mode, you can pass 
a “gatename” to your LIM. The interface can then use 
this function to establish routing for all subsequent 
function codes to a given subroutine. 


This technique is useful when existing subroutine 
packages have overlapping function codes. By 
switching all function requests through a specified 
gateway until a new “gateway” is requested, you can 
access a variety of external functions through a 
common call architecture. 


Revised Call Support for the 
Personal Computer 


The IBM-supplied LIMs are designed to provide a 
fixed-format, easy-to-use call format. You may wish to 
tailor the number or format of the parameters to your 
specifications. 


For example, calls to the interface use offsets into the 
host presentation space. As an ease-of-use feature, you 
may want to redesign the function calls to use a 
row/column format. 
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In that case your LIM would convert the row/column data 
into the offset values required by the actual interface 
function module. 


Other revisions you might make to the call architecture 
could include: 


e Restrict certain functions from your application 
programmers. 


e Set up the session parameters automatically. 
e Do extended validity checking of function calls. 


e Make revisions in the call structure to fit your 
requirements. 


e Provide support for different data formats. 


Details of Writing Your Own 
Language Interface Module 


The LIM is responsible for building a parameter control 
block with the requisite data and issuing an Interrupt hex 
7F to call the function module. Before issuing the 
Interrupt hex 7F, you must set register AX to hex 0104 
and should set register BX to 0. 
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As a good programming technique, you should verify that 
an interrupt vector has been established for the interface’s 
EEHLLAPI.EXE module. The parameter control block 
has the following format: 


PCB_HDR DB ' 
PCB_FUNC DB 0 
PCB_DSEG DW ce) 
PCB_DADDR DW 0 
PCB_LENGTH DW 0 +Data length VALUE 
PCB_FILLER DB 0 
PCB_RETCODE DW 0 
PCB_STRLEN DW 2 


PCB' ;PCB Header (in Caps) 
;Function code VALUE 
;String seg addr 
;String offset addr 


;Unused 
;Return code VALUE 
5000 ;Maximum user string size 


These rules apply in building the parameter control block: 


The control block header PCB (in upper case) must 
appear at the start of the control block. 


The function code must be the 1-byte numeric (binary) 
function code. 


The pointer to the user’s data string must contain the 
segment and offset address (note that the segment 
address precedes the offset). 


The string pointer should point to the actual data 
string, and not to a length or pointer prefix. 


The length should be the actual binary length value 
passed by the user. Since some function calls pass 
data in the fourth parameter (normally the return 
code), this value should be passed in the parameter 
control block. 


The string length field contains the actual length of 
the user’s string, if the language you are using to write 
your EEHLLAPI program provides a length value. 
This allows the code to avoid overlays by checking the 
length before placing data in the string. This field is 
only used by languages such as BASIC that provide 
the string length in the linkage data. 
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If your language does not provide the allocated length 
of a string, default this to 25000. 


e There are special considerations for Storage Manager 
calls. The internal interface to the storage manager is 
different from the regular EEHLLAPI interface. The 
storage manager shares the 7F interrupt vector, but 
does not use a PCB call. It has a register interface. 
The LIM service layer remaps the standard format user 
call into this register interface. The storage manager 
interface is: 


INT 7FH 
Registers: AX - 0104H (mandatory) 
BX - rrAAH (BL must = AAhex), 
rr=01-04 request code 
(Ol=get, O2=free, 04=freeall) 
CX - storage size (on GET request) 
block ID (on FREE request) 


Returns: 
Call: 01 (get): CX=block ID, DX=RETC 
AX=storage seg 
BX=offset 
02 (free): DX=RETC 
04 (free all) DX=RETC 


Note: The storage manager uses a register interface, 
not the EEHLLAPI PCB. The support for 
function 17 is handled at the LIM level. 
IBM-supplied LIMs support this call. 
User-supplied LIMs may or may not provide this 
feature. 


Once the control block is built, call the resident module 
with the INT hex 7F interrupt. The DS:SI registers should 
point to the control block. You should save any required 
non-segment registers. After executing the requested 
function, control is returned to your next sequential 
instruction after the INT hex 7F. The return code and 
any result codes are passed back to the parameter control 
block. You should pass these values back to the 
application caller’s data area. 
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Note that EEHLLAPI passes the string data back directly, 
but the return code is passed back to the parameter 
control block, and you must retain the user’s data 
addresses and pass back the return and result codes. This 
allows you to examine and, if necessary, reformat these 
values. 


Appendix B. Writing Your Own LIM B-9 


Notes 


B-10 Programming Guide 


Appendix C 


Appendix C. OIA Image and Bit 
Group Information 


This appendix explains Positions 2 through 81 and 82 
through 103 in the host Operator Information Area (OIA). 
This information is vital to interpreting the returned data 
string under Function 13 Copy OIA. 


OIA Image Group (Positions 2 
through 81) 


The meaning of symbols in the OIA Image Group are 
understood by looking up the desired hexadecimal code in 
Figure C-1 “Host Presentation Space Character Table” on 
page C-2. This figure shows the hexadecimal codes found 
in the host presentation space, and the characters they 
represent. Refer to the IBM PC 3270 Emulation Program, 
Entry Level, User’s Guide for information on the OIA 
indicators. 
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Figure C-1. Host Presentation Space Character Table 
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OIA Group Indicator Meanings 
(Positions 82-103) 


The states of each group are ordered so that the high 
order bits represent the indicators of higher priority. 
Therefore, if more than one state is active within a group, 
the state with the highest priority is the active state 
within that group. 


Bytes 1 and 5 from Group 8 are used for the Entry Level 
Emulation Program. The remaining bytes and Groups are 
reserved. 


Group 8: Input inhibited (5 bytes) 


Byte 1: 


Bit 
0-1 


Meaning 

Reserved 

Machine check 
Communications check 
Program check 
Reserved 


Meaning 
Reserved 
Application program has operator input 
inhibited 
Reserved 
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Appendix D. Related Publications 


Although it is assumed that you are familiar with the 
operation of the Personal Computer and the related 
languages, you may wish to refer to the publications listed 
below: 

IBM PC Disk Operating System 

IBM PC Disk Operating System Technical Reference 


IBM Personal Computer Language Series: C Compiler 
Compile, Link and Run 


IBM PC BASIC Manual 

IBM PC BASIC Compiler Manual 
IBM PC COBOL Reference 

IBM PC PASCAL Manual 

IBM PC Macro Assembler Manual 


IBM PC 3270 Emulation Program, Entry Level, User’s 
Guide 


IBM 3270 PC High Level Language Application 
Program Interface, Programming Guide. 
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Appendix E. Sample Programs 


This appendix contains code samples. The tables 
appearing before the sample programs list the functions 
used in the sample. 


BASIC Sample Program 


: Function Number 


10 REM EEHLLAPI Version 1.XX 
20 REM SAMPLE PROGRAM 
30 REM (c) COPYRIGHT 1986,1987, IBM CORPORATION 
40 KEY OFF: CLS 
“ 


50 LOCATE 1,10 : PRINT EEHLLAPI SAMPLE BASIC PROGRAM” 


60 LOCATE 2,10 : PRINT “(c)Copyright 1986,1987 IBM Corporation” 
70 CLEAR 

80 REM This sample basic program uses EEHLLAPI to provide an 

90 REM interface to the user for downloading multiple files 

100 REM from the host. 

110 REM --n rrr nr rr rrr rr rrr rrr rrr er tn cscs cco 
120 REM *** MANDATORY INT BASIC INITIALIZATION **** 

130 REM qn rrr rrr rr rrr eet errr ca 
140 DEF SEG O: APILOC=PEEK(&H1FE) + PEEK(&H1FF) 


150 IF APILOC = O THEN PRINT “FEHLLAPI IS NOT AVAILABLE”: END 
160 DATA &HO4B8, SHB301, &HCDBB, SHCA7F, &HOOO2 

170 DIM APICALL% (4) 

180 FOR I=0 TO 4: READ APICALL%S(I): NEXT I 
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190 
200 
210 


220 
230 
240 
250 
260 
270 
280 
290 
300 
310 
320 


330 
340 
350 


360 
370 
380 
390 
400 
410 
420 
430 
440 
450 


460 
470 


480 
490 
500 
510 
520 
530 
540 


550 
560 
570 
580 


590 
600 
610 
620 
630 
640 
650 


660 
670 
680 
690 
700 
710 
720 


730 
740 
750 
760 


770 
780 


BLIMSET = VARPTR (APICALL%(0) ) 
DEF SEG: CALL BLIMSET (APICALL%(1) ) 
BLIM=APICALL%$(1): DEF SEG = APICALL%(0) 


IF BLIM = &HB301 THEN PRINT “EEHLLAPI NOT AVAILABLE”: END 
REM) S--=-+ 5 ae eee oo ee eet eee sk 
REM *** END OF REQUIRED INIT. LOGIC *** 


REM --~--------------------------------------- n-ne 
GOTO 380 

REM --~--7 Common routine to call EEHLLAPI ---------------- 
CALL BLIM (FUNC% ,SDATAS , DLEN%, RETC%) 


IF RETC% = 9 AND FUNC% <> 99 THEN GOTO 310 


RETURN 

REM --- System Error --- 

CLS 

PRINT “A System Error was detected during function:” ;FUNC% 
FUNC%=20: SDATA$ = SPACES(35) 

CALL BLIM (FUNC%,SDATAS , DLEN% , RETC%) 


PRINT “Error component information =”, MIDS (SDATAS , 20,8) 


FUNC% = 21 

GOSUB 270 

REM -s--eense Cees eda Secon Sete ceeees 

CLS 

LOCATE 5,5 : PRINT “Drive # (1..26) for RECEIVE.COM’; 


cs 


Input “ ; ” ,DRIVE% 


66,9? 


HOSTS = E 

REM >>> Connect to Host Session 

REM ============s== CONNECT ====S====3=S=S=== 
FUNC% = 1 

SDATAS = HOSTS 

GOSUB 270 

REM ---~----------------------------------- 


IF RETCS <> 0 THEN PRINT “Could not connect to host” : END 
REM >>> Clear Host Screen 

REM SsessseSssssSSSsSS SENDKEY ct +t Ft _+ $f tt 4 

FUNC% = 3 
SDATAS = “@C 
DLEN% = 2 
GOSUB 270 


REM: =-2=<S2=> PROMPT FOR FILE SPECS --------- 
LOCATE 5,1 
” 


PRINT “Please input the info for files to be '; 
PRINT “considered for downloading from the host.” 
PRINT “Use the wild card character (*) in order we 
PRINT “to consider a group of files.” 

LOCATE 11,15: INPUT “filename : ”,FILENAMES 
LOCATE 13,15: INPUT “filetype : ”,FILETYPES 


LOCATE 15,15: INPUT “filemode : ”,FILEMODES 


9? ce 


FILELIST$ = FILENAMES + + FILETYPES + + FILEMODES 
REM >>> Filelist Command 
REM sse<e=s2s======= SENDKEY ======S======== 
FUNC% = 3 
“ce . P 3” “ce bea 
SDATAS = filelist + FILELISTS + @E 
DLEN% = LEN(SDATAS) 
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790 
800 
810 
820 
830 
840 
850 
860 
870 
880 


890 
900 
910 
920 
930 


940 
950 
960 


970 
980 
990 
1000 


1010 
1020 
1030 
1040 
1050 
1060 
1070 
1080 


1090 
1100 
1110 
1120 
1130 
1140 


1150 
1160 
1170 
1180 
1190 
1200 


1210 
1220 
1230 
1240 
1250 
1260 
1270 
1280 


1290 
1300 
1310 
1320 
1330 
1340 
1350 
1360 
1370 


1380 


BASIC Sample Program 


GOSUB 270 
REM $23 -sn ase eos e a saan saan s eee nanso- 
REM >>> Wait for Host to execute filelist command 
REM SssssssesssrssSsssS WAIT Fey fy ft ee ye fy ff ey 
FUNCS = 4 
GOSUB 270 
REM ~~ were rn nnn nnn nnn ce easess- 
REM >>> Determine Position of Header Field 
REM ========= FIND FIELD POSITION ========= 
FUNC% = 31 

“ 2”? 
SDATAS = N 
RETCS = 1 
GOSUB 270 
REM corn nn ne nnn nnn een nn nnn een rrr an- 
IF RETC% = 0 THEN GOTO 950 


PRINT “Could not find position of header field” 


FPOS% = DLEN% 
IF FPOS% < 200 THEN GOTO 980 


PRINT “Found bad header field position” : END 
REM >>> Determine Size of Header Field 

REM ========== FIND FIELD LENGTH ========== 
FUNC% = 32 


” 


SDATAS = “T 

RETC% = FPOS% 

GOSUB 270 

REM <90-~----- 2-020 en 
FLEN% = DLEN% 

REM >>> Search Header Field for 'Filename' 
REM SSeS Ssses5S>555=>=> SRCH FIELD ============= 
FUNC% = 30 

SDATAS = “Filename” 

DLEN% = 8 

RETC% = FPOS% 

GOSUB 270 

REM - 922 oe nonin nner nn nnn rn nnn nnn 


IF RETC% <> 24 THEN GOTO 1160 


PRINT “Could not find header string” : END 

REM >>> The file info (name,type,mode) in 

REM >>> each field begins under 'Filename' 

OFFSETS = DLEN% —- FPOS% 

CLS 

LOCATE 4,1 

PRINT “Please jump to your Host session and 

PRINT “put an asterisk (*) in the cmd field 
> 


PRINT “for each file that you would like §; 
PRINT “downloaded from the host. The set ” 


9 


bed 


PRINT “of files to be downloaded must include ” 
PRINT “the first file and any number of i 
PRINT “consecutive files after the first. ”. 
PRINT “Then jump back to your PC session and ms 
INPUT “oress enter to continue. . 2” XS 

CLS 

REM --- =SSess=sSSSSSsssSSSSSSSss5=== aa 

REM --- BEGIN LOOP GET/TRANSFER FILE --- 

REM oe SSS SSS SS SS SSS SS SSS SSS SSS SSS 

CLS 

REM >>> Find the beginning of the next field 
REM ========= FIND FIELD POSITION ========= 
FUNC% = 31 


92 


spatas = “Nn 


: END 


' 
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1390 RETC% = FPOS% 

1400 GOSUB 270 

1410 REM ---~------------------~---------------- 
1420 IF RETC% = 0 THEN GOTO 1440 


1430 PRINT “could not find next field” : END 
1440 FPOS% = DLENS 


1450 IF FPOS% > 1441 THEN PRINT “Bad Field” : END 
1460 REM >>> Search cmd field for flag * 

1470 REM ==========s==== SRCH FIELD =====s======== 
1480 FUNC% = 30 


1490 SDATAS = * 

1500 DLEN% = 1 

1510 RETC% = FPOS% 

1520 GOSUB 270 

1530 REM sonnet rr tre rene see = 
1540 REM >>> If no flag, then all done 

1550 IF RETC% = 24 THEN GOTO 2150 

1560 REM >>> Copy file info from field 


1570 REM ========= COPY FIELD TO STRING ======== 
1580 FUNC% = 34 
1590 DLEN% = FLEN% 


1600 SDATAS = SPACES (DLEN%) 
1610 RETC% = FPOS% + OFFSET% 
1620 GOSUB 270 


1630 REM ----~--~----------~---------------------- 
1640 HOSTFILES = MIDS$(SDATAS,OFFSET% + 1,20) 
1650 REM ~-- remove spaces from file spec string --~ 


” 


1660 TEMP% = INSTR(HOSTFILES,“ ”) 

1670 IF TEMP% = 0 THEN GOTO 1720 

1680 TEMP1$ = MID$(HOSTFILES,1,TEMP%) 

1690 TEMP2$ = MID$(HOSTFILES,TEMP% + 2,LEN(HOSTFILES) ) 
1700 HOSTFILES = TEMP1$ + TEMP2$ 

1710 GOTO 1660 

1720 REM --~ Get PC File specs --- 

1730 CLS 


1740 LOCATE 5,5 : PRINT “DOWNLOADING : 
1750 LOCATE 7,25: PRINT HOSTFILES 
1760 LOCATE 10,5 


1770 PRINT “Please input PC file specifications.’ 
1780 LOCATE 11,5 


1790 PRINT “If you specify a path, be aan 
1800 PRINT “be sure that the path ends in -” 


” 


? 


1810 LOCATE 13,15: INPUT “path : ”, PCPATHS 

1820 LOCATE 15,15: INPUT “filename : ”,PCNAMES 

1830 LOCATE 17,15: INPUT “filetype : ”,PCTYPES 

1840 PCFILE$ = PCPATH$ + PCNAMES + “.” + PCTYPES 

1850 LOCATE 19,15: INPUT “options : ”, OPTIONS$ 

1860 OPTIONSS = “(” + OPTIONSS 

1870 REM >>> Must Disconnect in order to call Function 91 
1880 REM ============= DISCONNECT ======s====s==== 


1890 FUNC% = 2 
1900 GOSUB 270 


1910 REM ---------~-------+-~--~----------+--------- 

1920 CLS 

1930 LOCATE 1,1 

1940 PRINT “Downloading : ”;HOSTFILE$;“ to ”;PCFILE$ 
1950 LOCATE 3,1 

1960 REM ============= RECEIVE FILE ============ 

1970 FUNC% = 91 

1980 SDATAS = PCFILES + “ ” + HOSTFILES + “ ” + OPTIONSS 
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DLEN% = LEN(SDATAS) 
RETC% = DRIVE% 
GOSUB 270 
REM -oo corr nen nnn nna 
LOCATE 24,10 : INPUT “Press Enter to continue....”,X$ 
REM >>> Reconnect to Host Session 
REM ====s=========== CONNECT Sssssssesssssee= 
FUNC% = 1 
SDATAS = HOSTS 
GOSUB 270 . 
REM ------ 99 nn nnn nnn nnn nnn 
GOTO 1310 
REM eee SS Ps2Ss2 S288 S22 2535S S532 522SES2E22 e2°— 
REM --- END LOOP GET/TRANSFER FILE --- 
REM eee SP trtss2 2 SesSeS sss sss sss sess HH = 
REM >>> Get out of filelist screen 
REM =2==22=s========== SENDKEY 3=========S==S=== 
FUNC% = 3 

6 ” 
SDATAS = @3 
DLEN% = 2 
GOSUB 270 
REM ----- 902 onn nnn nnn 
REM >>> Reset System to known state (Disconnect, etc.) 
REM ============ RESET SYSTEM ============= 
FUNC% = 21 
GOSUB 270 
REM soon tenn nnn nner nnn nnn nnn nee 
CLS 
LOCATE 2,5 : PRINT “DOWNLOADING IS COMPLETED” 
LOCATE 5,5 : INPUT “(b) BASICA or (d) DOS ? ”,SCONTS 


CLS 
IF sconts$ = “b” THEN GOTO 2330 


66 9? 


IF SCONT$ = d THEN GOTO 2340 
GOTO 2340 

KEY ON : END 

SYSTEM 
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COBOL Sample Program 


IDENTIFICATION DIVISION. 

PROGRAM-ID. SAMPLER. 

* This is a Cobol sampler program which allows 
* the user to test EEHLLAPI function calls. 
AUTHOR. PSC 

ENVIRONMENT DIVISION. 

DATA DIVISION. 

WORKING~STORAGE SECTION. 


*====GLOBAL VARIABLES====* 
77 CHOICE PIC 999. 
77 DLEN-DISPLAY PIC 9999. 
77 RETC-DISPLAY PIC 9999. 
*----EEHLLAPI PARAMETERS----* 
77 FUNC PIC 99 COMP-0O. 
77° DLEN PIC 99 COMP-O. 
77 RETC PIC 99 COMP-O. 
77  DATA-STR PIC X(80) VALUE SPACES. 
*----MISC INPUT STRINGS----* 
77 PSID-STR PIC X VALUE SPACES. 
77° EMPTY-STR PIC X(80) VALUE SPACES. 
O01 HOST-EVENT-BUFF. 
03 HE-PSID PIC X VALUE '' '. 
03 HE-TYPE PIC X VALUE 'B'. 
03 HE-PTR PIC X(4) VALUE LOW-VALUES. 
03 FILLER PIC X(256). 


SCREEN SECTION. 

O1 NUMER-MENU. 

*----NUMERICAL LIST OF FUNCTIONS----* 
03 BLANK SCREEN. 


03 LINE 1 COLUMN 24 VALUE 'EEHLLAPI NUMERICAL MENU'. 
03 LINE 2 COLUMN 24 VALUE ‘se2s2222=2=s2=s=s=2===Ss===! , 
03 LINE 3 COLUMN 1 VALUE ' 1 =- Connect'. 

03 LINE 4 COLUMN 1 VALUE ' 2 - Disconnect'. 

03 LINE 5 COLUMN 1 VALUE ' 3 - Send Key'. 

03 LINE 6 COLUMN 1 VALUE ' 4 - Wait'. 

03 LINE 7 COLUMN 1 VALUE ' 6 - Search PS'. 

03 LINE 8 COLUMN 1 VALUE ' 7 - Q Cursor Location’. 
03 LINE 9% COLUMN 1 VALUE ' 8 - Copy PS to String’. 
03 LINE 10 COLUMN 1 VALUE ' 9 - Set Session Parms'. 
03 LINE 11 COLUMN 1 VALUE '10 - Q Sessions’. 

03 LINE 3 COLUMN 27 VALUE '11 - Reserve'. 

03 LINE 4 COLUMN 27 VALUE '12 - Release'. 

03 LINE 5 COLUMN 27 VALUE '13 - Copy OIA'. 

03 LINE 6 COLUMN 27 VALUE '14 - Q Field Attribute’. 
03 LINE 7 COLUMN 27 VALUE '15 - Copy String to PS'. 
03 LINE 8 COLUMN 27 VALUE '18 - Pause'. 

03 LINE 9 COLUMN 27 VALUE '20 - Q System’. 

03 LINE 10 COLUMN 27 VALUE '21 - Reset System'. 

03 LINE 11 COLUMN 27 VALUE '22 ~- Q Session Status’. 
03 LINE 3 COLUMN 53 VALUE '23 - Start Host Notify'. 
03 LINE 4 COLUMN 53 VALUE '24 - Q Host Update'. 

03 LINE 5 COLUMN 53 VALUE '25 - Stop Host Notify'. 
03 LINE 6 COLUMN 53 VALUE '30 - Search Field'. 

03 LINE 7 COLUMN 53 VALUE '31 - Find Field Pos.'. 
03 LINE 8 COLUMN 53 VALUE '32 - Find Field Length'. 
03 LINE 9 COLUMN 53. 


VALUE '33 - Copy String to Field’. 
03 LINE 10 COLUMN 53 
VALUE '34 - Copy Field to String'. 
03 LINE 11 COLUMN 53 VALUE '99 - Convert Pos/RowCol'. 
O01 CHOICE-SCR. 
*---~SELECTION SCREEN----* 
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bs This screen is used to prompt the user for the 

* desired function. It also presents the user with 

* choices for different menus and program termination. 
03 LINE 14 COLUMN 20 VALUE ‘Select a function: '. 


03 LINE 14 COLUMN 39 PIC 2Z9 TO CHOICE. 
O02 LINE 22 COLUMN 1 RLANK LINE. 


03 LINE 24 COLUMN 20 VALUE '300-Exit Sample Program’. 
*#—---PROMPT SCREENS -- 3-93-37 - 3-7-3 rrr nr nner 
Ol STRING-PROMPT. 
* This screen is used to prompt the user for the 
* Data String calling parameter. 
03 LINE 15 COLUMN 13 VALUE 'String : ' 
03 LINE 15 COLUMN 23 PIC X(55) TO DATA- STR. 
Ol PSID-PROMPT. 
* This screen is used to prompt the user for the 
* Data String calling parameter when the Data String 
* only needs a PSID. 
03 LINE 15 COLUMN 13 VALUE 'PSID : '. 
03 LINE 15 COLUMN 21 PIC X TO PSID-STR. 
Ol HOST-~STR-PROMPT. 
* This screen is used to prompt the user for the 
* PSID and option code for function 23, Start Host 
* Notification. 
03 LINE 15 COLUMN 13 VALUE 'PSID: '. 
03 LINE 15 COLUMN 21 PIC X TO HE-PSID. 
03 LINE 15 COLUMN 25 VALUE ‘option code : '. 
03 LINE 15 COLUMN 39 PIC X TO HE-TYPE. 
QO1 LENGTH-PROMPT. 
* This screen is used to prompt the user for the 
* Length calling parameter. 

03 LINE 16 COLUMN 13 VALUE ‘Length : '! 

03 LINE 16 COLUMN 23 PIC 2229 TO DLEN Just. 
O1 RC-PROMPT. 
* This screen is used to prompt the user for the 
* PS Position/Return Code calling parameter. 

03 LINE 17 COLUMN 13 VALUE 'PS Position : ' 

03 LINE 17 COLUMN 28 PIC 2229 TO RETC JUST. 
*----DISPLAY SCREENS W373 3 nr nr rr rere nee 

OL STRING-DISPLAY. 
* This screen displays the returned Data String. 
03 LINE 19 COLUMN 13 VALUE ‘String : ' 
03 LINE 19 COLUMN 23 PIC X(55) FROM DATA- STR. 
Ol LENGTH-DISPLAY. 
7 This screen displays the returned Length. 
03 LINE 20 COLUMN 13 VALUE 'Length : ' 
03 LINE 20 COLUMN 23 PIC ZZZ9 FROM DLEN- DISPLAY. 
Ol RC-DISPLAY. 
* This screen displays the returned Return Code. 

03 LINE 21 COLUMN 13 VALUE 'Return Code : '. 

03 LINE 21 COLUMN 28 PIC ZZZ9 FROM RETC-DISPLAY. 
*—----MISCELLANEOUS SCREENS@-- 3-7-3 rrr nn rer rrr rrr 
Ol BLANK-SCR. 

03 BLANK SCREEN. 
Ol BLANK-LINE. 
03 BLANK LINE. 
Oi CONT-SCR. 
03 LINE 23 COLUMN 23 BELL REVERSE-VIDEO 
VALUE 'Press Enter to continue'. 
03 LINE 24 COLUMN 1 BLANK LINE. 
PROCEDURE DIVISION. 
MAIN-PARAGRAPH. 
This procedure displays a numerical list 
of the available functions and passes control 
to USERS-CHOICE for implementation of the 
desired function(s). 
DISPLAY NUMER~-MENU. 
GO TO USERS-CHOICE. 


* ee OF 
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USERS-CHOICE. 
* This procedure allows the user to test functions from 
x the current menu. It passes control for implementation 
‘3 of specific functions to the appropriate procedures. 
DISPLAY (14, 1) ERASE. 
MOVE O TO CHOICE. 
DISPLAY CHOICE-SCR. 
ACCEPT CHOICE-SCR. 
* Does the user want to exit the program? 
IF CHOICE = 300 GO TO DONE. 
*#~----TNITIALIZE VARIABLES-~-3- 33 3-rrrrerr rrrr rennn 
MOVE CHOICE TO FUNC. 
MOVE O TO DLEN RETC. 
MOVE EMPTY-STR TO DATA-STR. 
*---~PERFORM FUNCTION------- rn rer 
* This part of the procedure passes control to the 
bad appropriate procedure for implementing the desired 
* EEHLLAPI function. 


IF FUNC = 1 PERFORM CONNECT. 

IF FUNC = 2 PERFORM DISCONNECT. 

IF FUNC = 3 PERFORM SENDKEY. 

IF FUNC = 4 PERFORM WAIT. 

IF FUNC = 6 PERFORM SEARCH-PS. 

IF FUNC = 7 PERFORM Q-CURSOR-LOC. 

IF FUNC = 8 PERFORM COPY-PS-STRING. 

IF FUNC = 9 PERFORM SET-SESSION-PARMS. 
IF FUNC = 10 PERFORM QUERY-SESSIONS. 

IF FUNC = 11 PERFORM RESERVE-KEYBD. 

IF FUNC = 12 PERFORM RELEASE-KEYBD. 

IF FUNC = 13 PERFORM COPY-OIA. 

IF FUNC = 14 PERFORM Q-FIELD-~ATTRIB. 

IF FUNC = 15 PERFORM COPY-STRING-PS. 

IF FUNC = 18 PERFORM PAUSE. 

IF FUNC = 20 PERFORM Q-SYSTEM. 

IF FUNC = 21 PERFORM RESET-SYSTEM. 

IF FUNC = 22 PERFORM Q-SESS-STATUS. 

IF FUNC = 23 PERFORM START-HOST. 

IF FUNC = 24 PERFORM Q~-HOST. 

IF FUNC = 25 PERFORM STOP-HOST. 

IF FUNC = 30 PERFORM SEARCH-FIELD. 

IF FUNC = 31 PERFORM FIND-FIELD~LENGTH-POS. 
IF FUNC = 32 PERFORM FIND-FIELD-LENGTH-POS. 
IF FUNC = 33 PERFORM COPY-STRING-FIELD. 
IF FUNC = 34 PERFORM COPY-FIELD-STRING. 
IF FUNC = 99 PERFORM CONVERT-POS-ROWCOL. 


*-~~--DISPLAY RETURN CODE AND PAUSE------~--------------=-=- 
bd After any EEHLLAPI function call, we want to see 
= the Return Code and pause to examine the parameters 
* passed and returned. 

DISPLAY RC-DISPLAY. 

DISPLAY CONT-SCR. 

DISPLAY (23, 1) ' Lae 

STOP ' '. 

GO TO USERS-CHOICE. 
*====EEHLLAPI FUNCTIONS=============SSSSSSSSSeeee55SS5555 
bs These procedures control the implementation of 
* specific EEHLLAPI function calls. Procedure calls 
af are made to the miscellaneous IO procedures for the 
* prompting and displaying of parameters. 
CONNECT. 

PERFORM GET-PSID. 

PERFORM EEHLLAPI-CALL. 
CONVERT~POS-ROWCOL. : 

PERFORM GET-STRING. 

PERFORM GET-LENGTH. 

PERFORM GET-RC. 

PERFORM EEHLLAPI-CALL. 

DISPLAY LENGTH-DISPLAY. 
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COPY-FIELD-STRING. 
PERFORM GET-LENGTH. 
PERFORM GET-RC. 
PERFORM EEHLLAPI-CALL. 


DISPLAY STRING-DISPLAY. 


COPY-OIA. 

PERFORM GET-LENGTH. 

PERFORM EEHLLAPI-CALL. 

DISPLAY STRING-DISPLAY 
COPY-PS-STRING. 

PERFORM GET-LENGTH. 

PERFORM GET-RC. 

PERFORM EEHLLAPI-CALL. 

DISPLAY STRING-DISPLAY 
COPY-STRING-FIELD. 

PERFORM GET-STRING. 

PERFORM GET-LENGTH. 

PERFORM GET-RC. 

PERFORM EEHLLAPI-CALL. 
COPY-STRING-PS. 

PERFORM GET-STRING. 

PERFORM GET-LENGTH. 

PERFORM GET-RC. 

PERFORM EEHLLAPI-CALL. 
DISCONNECT. 

PERFORM EEHLLAPI-CALL. 
FIND-FIELD-LENGTH-POS. 

PERFORM GET-STRING. 

PERFORM GET-RC. 

PERFORM EEHLLAPI-CALL. 

DISPLAY LENGTH-DISPLAY 
PAUSE. 

PERFORM GET-LENGTH. 

PERFORM EEHLLAPI-CALL. 
Q-CURSOR-LOC. 

PERFORM EEHLLAPI-CALL. 

DISPLAY LENGTH-DISPLAY 
Q-FIELD-ATTRIB. 

PERFORM GET-RC. 

PERFORM EEHLLAPI-CALL. 

DISPLAY LENGTH-DISPLAY 
Q-HOST. 

PERFORM GET-PSID. 

PERFORM EEHLLAPI-CALL. 
QUERY-SESSIONS. 

MOVE 24 TO DLEN. 

PERFORM EEHLLAPI-CALL. 

DISPLAY LENGTH-DISPLAY 

DISPLAY STRING-DISPLAY 
Q-SESS-STATUS. 

PERFORM GET-PSID. 

MOVE 18 TO DLEN. 

PERFORM EEHLLAPI-CALL. 

DISPLAY STRING-DISPLAY 
Q-SYSTEM. 

PERFORM EEHLLAPI-CALL. 

DISPLAY STRING-DISPLAY 
RELEASE-KEYBD. 

PERFORM EEHLLAPI-CALL. 
RESERVE-KEYBD. 

PERFORM EEHLLAPI-CALL. 
RESET-SYSTEM. 

PERFORM EEHLLAPI-CALL. 
SEARCH-FIELD. 

PERFORM GET-STRING. 

PERFORM GET-LENGTH. 

PERFORM GET-RC. 

PERFORM EEHLLAPI-CALL. 


. 
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DISPLAY LENGTH-DISPLAY. 
SEARCH-PS. 
PERFORM GET-STRING. 
PERFORM GET-LENGTH. 
PERFORM EEHLLAPI-CALL. 
DISPLAY LENGTH-DISPLAY. 
SENDKEY. 
PERFORM GET-STRING. 
PERFORM GET-LENGTH. 
PERFORM EEHLLAPI-CALL. 
SET-SESSION-PARMS. 
PERFORM GET-STRING. 
PERFORM GET-LENGTH. 
PERFORM EEHLLAPI-CALL. 
START-HOST. 
PERFORM GET-HOST~STR. 
MOVE LOW-VALUES TO HE-PTR. 
MOVE 256 TO DLEN. 
CALL 'COBLIM' USING FUNC HOST-EVENT-BUFF DLEN RETC. 
STOP-HOST. 
PERFORM GET-PSID. 
PERFORM EEHLLAPI-CALL. 
WAIT. 
PERFORM EEHLLAPI-CALL. 
*====GENERIC EEHLLAPI CALL=====2232=s=S==S==S=S====sSs2222== 
* This is the EEHLLAPI function call used by most of 
* the above procedures. This procedure also moves the 
* returned parameters into variables used for display. 
EEHLLAPI-CALL. 
CALL 'HLLCOB' USING FUNC DATA-STR DLEN RETC. 
MOVE DLEN TO DLEN-DISPLAY. 
MOVE RETC TO RETC~DISPLAY. 
*k====MISCELLANEOUS ROUTINES=========S=ssss2=2==S=S=S===S==S===25 
GET-STRING. 
* This procedure prompts the user for the Data String. 
DISPLAY STRING-PROMPT. 
ACCEPT STRING-PROMPT. 


GET-PSID. 
- This procedure prompts the user for the Data String 
sal in the case where the Data String requires only a PSID. 


DISPLAY PSID-PROMPT. 
ACCEPT PSID-PROMPT. 
MOVE PSID-STR TO DATA-STR. 
GET-HOST~STR. 
7 This procedure prompts the user for the Data String 
* needed for function 23, Start Host Notification. 
DISPLAY HOST-STR-PROMPT. 
ACCEPT HOST-STR-PROMPT. 
GET-LENGTH. 
* This procedure prompts the user for the Length. 
DISPLAY LENGTH-PROMPT. 
ACCEPT LENGTH-PROMPT. 
GET-RC. 
* This procedure prompts the user for the PS Position. 
DISPLAY RC-PROMPT. 
ACCEPT RC-PROMPT. 
DONE. 
* This procedure clears the screen and 
7 terminates the program. 
DISPLAY BLANK-SCR. 
STOP RUN. 
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Function Number 
Copy Presentation Space to String 


Ee 
[Disconnect 
[Query System 0 
[Search Presentation Space ———SCSC~d SSS 


program set_time ( input, output); 


(* sone nere------ SAMPLE EEHLLAPI PROGRAM -----<-<srseerren- *) 
(* This program is designed to obtain the time and date *) 
(* information from the host session and pass this *) 
(* information to the PC session. He 
const 

(* (ee ee ee ee eee we we wee eee ee a ee eee we wee ee ee * 


(* KEYBOARD MNEMONICS * 
(* These mnemonics are only valid as long as the escape * 
(* character is not changed from its default value of '@' * 
(* with a call to Set Session Parameters. * 


(* ee ee ne we ee a a a a a * 
clear_key = '@C'; 
enter_key = '@E'; 
reset_key = '@R'; 


(Renweene seas a - sa 5-4 +--+ +--+ - = *) 
(* date and time record types for passing *) 
(* information to PC Session * 


time_record = record 
hour , 
min , 
sec , 
tick : integer; 
end; 
date_record = record 
year , 
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month , 
day : integer; 
end; 


var 
(* EEHLLAPI calling parameters : *) 
Function _Number : integer; 
Data_String : string(144); 
Length : integer; 
Return_Code : integer; 
(* --- strings containing time and date information --- *) 
time_string, * time : hh:mm:ss *) 
date_string : lstring(8); (* date : mm/dd/yy *) 
(* =-- records containing time and date information --- *) 
time : time_record; 
date : date_record; 
(* --- PSID of Host Session determined during init --- *) 


Host_Session : char; 


(* External reference to call EEHLLAPI Pascal LIM *) 
procedure HLLPAS ( var lim_func : integer; 

var lim_str : string; 

var lim_len, 

lim_retc : integer ); EXTERN; 


(* External references to Pascal library functions for * 
(* setting the time and date. See the Pascal Compiler * 
(* Language Reference for more information on how to * 
(* use these functions. * 


function setdat (year,month,day : integer) 
boolean; EXTERN; 

function settim (hours,minutes,seconds,hundreds : integer) 
boolean; EXTERN; 


(* External reference to Pascal library procedure for * 
(* terminating the program. See the Pascal Compiler 7 
(* Language Reference for more information on how to - 
(* use this functions. 


procedure ENDXQQ; EXTERN; 


procedure check_system; 

(* ne ee a a a a en we ee ee we we ew ee a wo ee *) 
(* This procedure should be called after any call to EEHLLAPI. *) 
(* This procedure determines whether or not there was a system *) 
(* error (return code of 9 from EEHLLAPI). If a system error *) 


(* did occur, then system information is obtained through a *) 
(* call to Query System and program execution is halted. *) 
(SSeS 2220 (Se eae ee ee et ee Se ee *) 
var 

i: integer; 
begin 


if Return_Code = 9 then begin 
writeln('There was a system error.'); 
writeln('Calling Query System to get system info.'); 
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(* ======== Query System ====s==== *) 

Function_Number := 20; 

HLLPAS ( Function_Number, 
Data_String, 


Length, 
Return_Code ); 
if Return Code = 9 then 


writeln('Unrecoverable System Error. ') 
else begin 
writeln('<<< SYSTEM DATA >>>'); 


write(' Bytes 1 to 15 2 ')y 

for i := 1 to 15 do write(Data_String{i}); 
writeln; 

write(' Extended Error Code 1: '); 
for i := 20 to 23 do write(Data_String{i}); 
writeln; 

write(' Extended Error Code 2: '); 
for i := 24 to 27 do write(Data_String{i}); 


writeln; 
end; (* of else *) 
(* stop execution and return to DOS *) 
ENDXQQ; 
end 
end; 


procedure set_Host Session; 


) 
(* This procedure calls the EEHLLAPI function Query Sessions *) 
(* in order to determine the short name of the host session. *) 
(* The global variable 'Host_Session' is set accordingly. *) 

) 


(* ee mee ce cee me me ee a a a a a ee ee eee * 
var 

offset, (* offset to the beginning of the *) 

(* 12 bytes of info per session; *) 

i: integer; (* loop control variable *) 
begin 

(* sess Query Sessions ======= *) 

Function_Number := 10; 

Length := 144; 


HLLPAS ( Function_Number, 
Data_String, 
Length, 
Return_Code ); 
check_system; 
(* Note : # of sessions is returned in Length *) 
(* check each session to see if it is the host session *) 
for i := 1 to Length do begin 
(* calculate offset to ith session *) 
offset := (i - 1) * 12 ; 
(* session type is returned in 10th position *) 
if Data_String{offset+10} = 'H' then 
Host Session := Data_String{offsett+1}; 
end; (* of for loop *) 
end; 


function digit ( ch : char ) : integer; 


(* This function converts a digit in character form to * 
(* a digit in integer form. * 
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digit := ord(ch) - ord('0O') ; 
end; 


procedure convert_info; 

(* a ee ee ee me ee eee ca ee ewe ere ee ee ee ee ee we ee ee 
(* This procedure is used to convert the time and date strings 

(* into integer values so that they may be passed to DOS using 

(* the Pascal function calls 'settim', and 'setdat'. The 

(* values are stored in records, the global variables 'time' 

(* and ‘date’. 


(* Sew e eck ces ee awe ee ewes ee eee ee a Se ee ee eee SS Se ee 
begin 
time-hour := 10 * digit(time_string[1]) + 
digit(time_string[2]) ; 
time.min := 10 * digit(time_string[4]) + 
digit(time_string[5]) ; 
time.sec := 10 * digit(time_string[7]) + 
digit(time_string[8]) ; 
time.tick := 0; 
date.month := 10 * digit(date_string[1]) + 
digit(date string[2]) ; 
date.day := 10 * digit(date_string[4]) + 
digit(date_string[5]) ; 
date.year := 10 * digit(date_string[7]) + 
digit (date_string[8]) + 
1900; 
end; 


procedure get_info ( const delimiter : lstring ; 
: ; 


var info_string string ); 

(* a we we ere *) 
(* This procedure searches the host screen for the given *) 
(* delimiter. If the delimiter is found, then the string of *) 
(* of info ( time or date ) is copied into the given string *) 
(* variable. *) 
(* ee ee ee en re eee ee ee Be ee em me mene ee eee eee ee eee we *) 
var 

delimiter_position : integer; 
begin 

(* = Search Presentation Space == *) 

Function Number := 6; 


copystr (delimiter ,Data_String) ; 
Length := 1; 
Return_Code := 1; 
HLLPAS ( Function_Number, 
Data_String, 
Length, 
Return_Code ); 
check_system; 


(* Note : position of string is returned in Length *) 
delimiter_position := Length; 
(* If the delimiter was found then copy the info *) 
if delimiter_position > 0 then begin 
(* ====== Copy PS to String ===== *) 
Function_Number := 8; 
Length := 8; 
Return_Code := 
delimiter_position - 2; 
‘ HLLPAS ( Function _Number, 
info_string, 
Length, 
Return_Code ); 
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check_system; 


end; (* of if *) 
end; 


(* This procedure attempts to query the host for the time. *) 


(Bessa a3 nln ne ei ne ee oe eee eee *) 
var 

cursor_location : integer; 
begin 

(* ssesssssss Send Key sesssesoso== *) 

Function_Number := 3; 


copystr (clear key,DataString) ; 
Length := 2; 
HLLPAS ( Function_Number, 
Data_String, 
Length, 
Return_Code ); 
check_system; 


(* =s<o55=>>S>==>== Wait ==> 555=== *) 
Function_Number := 4; 
HLLPAS ( Function_Number, 
Data_String, 
Length, 


Return_Code ); 
check_system; 


(* =====Search Presentation Space===== *) 
Function_Number :=6; 
copystr ('RUNNING' ,Data_String); 
Length := 7; 
Return_Code :=1; 
HLLPAS ( Function_Number, 
Data_String, 
Length, 
Return_Code ); 
check_system; 


(* s=oss====== Send Key seers sess= *) 

Function _Number := 3; 

copystr('query time '*enter_key,Data String) ; 
Length := 12; 


HLLPAS ( Function_Number, 
Data_String, 
Length, 
Return_Code ); 

check_system; 


(* ssoSSS>>5>=>=>=>= Wait Pa ey *) 
Function Number := 4; 
HLLPAS ( Function_Number, 
Data_String, 
Length, 
Return_Code ); : 
check_system; 


(* =====Search Presentation Space===== *) 
Function_Number :=6; 
copystr('RUNNING' ,Data_String); 
Length := 7; 
Return_Code := 1; 
HLLPAS ( Function_Number, 
Data_String, 
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Length, 
Return_Code ); 
check_system; 


getrinfo ( ':' , timeustring ); 
getwinfo ( '/' , date string ); 


end; 


procedure get time from host; 


(* This procedure calls ‘query for winfo' to obtain the time *) 
(* and date info from the host after it takes control of the * 


) 
(* Host Session. *) 
) 


set Host Session; 


(* Connect to Host and reserve keyboard *) 
* 


( Sesoes==== Connect =========== *) 
Function_Number := 1; 
copystr (Host _Session,Data String); 
Length := 1; 
HLLPAS ( Function_Number, 
Data_String, 
Length, 
Return_Code ); 
check_system; 
Function_Number := 11; 


HLLPAS ( Function_Number, 
Data_String, 
Length, 
Return_Code ); 

check_system; 


query for info; 
(* ==s======== Release ======s==== *) 
Function Number := 12; 


HLLPAS ( Function_Number, 
Data_String, 
Length, 
Return_Code ); 

check_system; 


(* sss====== Disconnect ===s===== *) 
Function_Number := 2; 
HLLPAS ( Function_Number, 
Data_String, 
Length, 
Return_Code ); 
check_system; 


end; 


procedure give time _to_PC; 


This procedure converts the time and date strings into *) 
the integer form that is passed to the Pascal settim and *) 
setdat functions. If the functions return a false value *) 
then a message is printed warning the user of the invalid *) 
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(* attempt to set the date and/or time. 
* 


begin ; 
convert_info; 
if not settim(time.hour,time.min,time.sec,time.tick) then 
writeln('Time not set.'); 
if not setdat(date.year,date.month,date.day) then 
writeln('Date not set.'); 
end; 


(* MAIN PROGRAM *)} 


begin 
(* sexexs==== Reset System ===SS=>==> *) 
Function_Number := 21; 


HLLPAS ( Function_Number, 
Data_String, 
Length, 
' Return_Code ); 
check_system; 


get _ time from uhost; 


give_time_to_PC; 
(* =s======= Reset System ee *) 
Function Number := 21; 


HLLPAS ( Function_Number, 
Data_String, 
Length, 
Return_Code ); 

check_system; 


end. 
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Function Number 
Convert Position or RowCol foo sssSY 


Query Cursor Location 7 
Query Field Attribute fies 


4 
2 
1 
1 


1 
1 


[BEER RRRRR ERE KERR RE RE EER EREE EER EERERER EERE REREREREREE / 
/* This sample C program is designed to use HLLAPI */ 
/7* to obtain position and attribute information of * 
* the cursor location. The user is prompted to */- 
* 
* 


/7* position the cursor accordingly, and is given 
/* the cursor position and a decoding of the field */ 
* 


/* attribute byte at that position. 
LEBER EKER REREREREREEREEREREREREERERRERERERERE / 


7* Include statement for standard input/output module */ 
#include <c:\ibmc\include\stdio.h> 


/* HLLAPI Parameters */ 
int APILFUNC, APILLEN, API_RETC; 
char API_STRING[255]; 


unsigned int shift (byte,numbits) 

/* This function returns the unsigned integer that */ 
/* results from shifting byte right numbits. If a */ 
/* negative number is passed throught the numbits */ 


/* parameter, byte is shifted left -numbits. */ 
unsigned int byte; 
ee numbits; 
unsigned int result; 
if (numbits > 0) 7* right shift */ 
result = byte >> numbits; 
else /* left shift */ 


result = byte << -numbits; 
return(result); 


void byte_to_bits (byte, bits) 
7* This function is designed to extract the 8 'bits' that */ 
/* define 'byte' and return them in the 'bits' array. */ 
unsigned int byte; 
short int bits[8]; 
{ 


unsigned int andbyte; 
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int i; 

unsigned int tempbyte; 

for ( i= 7, andbyte = 1; i >= 0; --i, andbyte *= 2 ) 
{ 


/* zero out all but ith bit */ 

tempbyte = byte & andbyte; 

/* shift ith bit to rightmost bit position */ 
ees = shift (tempbyte,7-i); 


void get iinfo () 
/7* This function obtains information regarding a 
/7* the attributes of the cursor location. 
{ 
7* cursor location info */ 
int cursor_pos, 
cursor_row, 
cursor_col, 
attribyte; 


/7* Connect to Host Session */ 
API_FUNC = 1; 


strcepy(API_STRING,“E\0”); 
API_LEN = 1; 
hllc(sAPI_FUNC,API_STRING, SAPI_LEN, &API_RETC) ; 
if (API_RETC != 0) 

{ 


printf (“warning : could not connect to Host.\n”); 


printf (“Return Code : %d\n”,API_RETC); 
return; 


, 


/* Reserve Keyboard */ 
API_FUNC = 11; 
hilc(&APIT FUNC, API.STRING, &API_LEN, &API_RETC) ; 


RREKKKEKREKKEEKEEKKKEKKEKKRKEKEE 


/* Query Cursor Location */ 
[BEERREREREEEEEREREREREEEE / 


API_FUNC = 7; 
hlilc(sAPI_FUNC,API_WSTRING, &API_LEN, &API_WRETC) ; 
if (APILRETC == 0) 

{ 

cursor pos = API_LEN; 


printf (“cursor Location : Position %d\n”,cursor_pos) ; 
else 
{ 
printf (“warning 3 7 
“could not determine cursor location.\n’); 


printf (“Return Code : %d\n”,API_RETC); 
return; 


, 


REKKKEEEKEKEKEEKKRKEKEKKKRKKRKKRKKE 


/* Convert Position to RowCol */ 
REAR E REEL RM ERE EE /- 


API_FUNC = 99; 


strepy(API_STRING, “EP\0”) ; 
APILRETC = cursor pos; 
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hllc(&API_LFUNC,API_STRING, &API_LEN, &API_RETC) ; 


if (APILRETC == 0 | | API_LLEN == 0) 
{ 
printf (“Warning : Incorrect input error.\n’); 
return; 


3 
else if (APILRETC == 9998) 
{ 


printf (“warning : "i 
“tnvalid Host id or Host never connected.\n”) ; 


return; 
} 
else if (API_LRETC == 9999) 
{ 
printf (“warning : input error in Data String\n”); 
return; 
else 
t ; 
cursor.wrow = APIVTLEN; cursor col = API.RETC; 


printf (“cursor Location : Row %d, Column d\n”, 
cursor row,cursor col) ;. 
} 


KRRKKEKKEKEKKKEKREKKEKKRREEKE 


7/* Query Field Attribute */ 
HH EKKERRERREKEKREREERE / 
API_FUNC = 14; 
APIWRETC = cursor pos; 
hllc(&API_FUNC,API_STRING, &API_LEN, &API_RETC) ; 
if (API_LEN == 0) 
{ 


printf(“The screen is unformatted.\n’); 
return; 


3 
else if (API_RETC != 0) 
{ 


printf (“could not determine the attribute byte.\n’); 
return; 
3 
else 
{ 
int i; 
/* attribute byte */ 
unsigned int attribyte; 
/* bit breakdown of attribute byte */ 
short int attribits[8]; 
short int attribit45; 


7* attribute byte is returned in length parameter */ 
attribyte = API_LEN; 


printf (“attribute byte (hex code) : %x\n”,attribyte) ; 
/7* break down attribyte into attribits */ 
byte_to.bits (attribyte,attribits); 


printf (“attribute byte (bin code) : ”); 
for ( i = 0; i <= 7; ++i 


printf (“sa” ,attribits[il); 
printf(“\n”); 
/7* Unprotected/Protected bit */ 
if (attribits[2] == 

printf (“Protected data field.\n”); 
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Unprotected data field.\n”); 


/* Alpha/Numeric bit */ 


if (attribits[3] == 1) 
printt(’ Numeric Gata only.\n’); 
else 
printf (“ Alphanumeric data.\n’”); 
/* Automatic skip */ 
if (attribits[2] ==1 && attribits[3] == 1) 
printé (“ Automatic skip.\n”); 
/* Intensity/Selector Pen Detectability bit */ 
attribit45 = (2 * attribits[4]) + attribits[5]; 
if (attribit45 == 0 ) 
{ 
printf (“ Normal intensity.\n”); 
printé (“ Not pen detectable.\n”); 
else if (attribit45 == 1) 
{ 
printt(“ Normal intensity.\n’); 
printf (“ Pen detectable.\n”); 
3 
else if (attribit45 == 2) 
{ 
printé (“ High intensity.\n”); 
printé (“ Pen detectable.\n”); 
} 
else if (attribit45 == 3) 
{ 
printé(“ Non-display.\n”); 
printf (“ Not pen detectable.\n”); 
3 


3 


/* Release Keyboard */ 
API_FUNC = 12; 
hllc(SAPI_ FUNC, API_STRING, &API_LEN, &APIO RETC) ; 


/* Disconnect from Host Session */ 
API_FUNC = 2; 
hlic(&API_FUNC,API_STRING, &API_LEN, &API_RETC) ; 


7* end of function get_info */ 


main() 


char ch; 

/* Reset System */ 

API_FUNC = 21; 

hllic(&API_FUNC,API_STRING, SAPI_LLEN, &API_RETC) ; 


do { 


printf (“\nPlease jump to your Host Session and move \n”); 
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“C” Sample Program 


printf (“the cursor to the desired location.\n”); 
printf (“Press 'i<RETURN>' to obtain info, or\n’); 


printf (“ 'q<RETURN>' to quit program. --> "yy 
ch = getchar(); 
getchar(); if (ch!='/012') getchar(); 
if (ch == 'i') get_info(); 
} 
while (ch != 'q'); 


/* Reset System */ 
API_FUNC = 21; 
hllc(&API_FUNC,API_STRING, &API_LEN, &API_RETC) ; 
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Appendix F. Glossary 


AID key. A control key that generates a host 
attention interrupt. 


American National Standard Code for 
Information Interchange (ASCII). One of the 
two standard codes used for exchanging 
information among data processing systems and 
associated equipment; the standard code used by 
the IBM Personal Computer and other 
microcomputers. 


attention identifier. See “AID key.” 


attribute byte. In 3270 application, the byte 
used for determining the characteristics of the 
following field (color, protected, highlighted). 


autoskip. A field defined as protected and 
numeric. Causes the cursor to skip to the next 
unprotected field. 


BASIC. Beginner’s All-Purpose Symbolic 
Instruction Code. A high-level, widely used 
computer programming language. 


EEHLLAPI.EXE. See “resident interface 
module.” 


extended error code. An eight-byte data string 
returned by Query System generated by an 
internal system error that is used by service 
personnel for diagnosis. 
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field. A group of consecutive positions on a 
presentation space with similar characteristics. 
These characteristics are defined by the field 
attribute byte at the beginning of the field. 


field-formatted presentation space. A 
presentation space which is made up of one or 
more fields. 


HLLAPI. High-Level Language Application 
Program Interface. 


language interface module (LIM). Programs 
provided by EEHLLAPI or that you can write 
that serve as bridges between your program and 
the resident interface module (HEHLLAPI.EXE) 
that passes parameters to the Entry Level 
Emulation Program. 


logging on. The procedure by which you are 
linked to a multiple-user host computer system; 
the procedure requires a user identification and 
generally a password. 


menu. A list of available operations. You 
select which operation you want from the list. 


NA. Not applicable. When this appears in a 
calling parameter position, it means that 
EEHLLAPI will not read the data in these fields. 


operator information area (OIA). The 
bottommost line of your screen where you receive 
information about the status of your host. 


presentation space (PS). An area in storage 
that corresponds to the image on your screen. 


presentation space position parameter. One 
of the four parameters that you must specify for 
each EEHLLAPI function. A position in the 
presentation space from 1 to 1920. 


F-2 Programming Guide 


Glossary 


programmed operator. The software “user” 
that performs and monitors activities in your PC 
without actual human intervention; your 
EEHLLAPIT application program. 


protected field. A field that is protected from 
modification by the operator. 


PS. See “presentation space.” 


PSID. Presentation Space Identifier; short 
one-character or one-letter name of the 
presentation space. 


resident interface module (KEEHLLAPI.EXE). 
The main interface module for EEHLLAPI, it 
must be loaded before you can use EEHLLAPI 
and must remain in storage as a resident 
extension of DOS. 


service coordinator. The person in your 
organization responsible for answering hardware 
and software computing questions. 


session. A connection between your work 
station and a host computer. (Contrast with 
“presentation space.”) 


short name. The one-letter name (A through Z) 
of the host presentation space. For the Entry 
Level Emulation Program this is always “E”. 


terminal operator. The human user of an 
EEHLLAPI application program (contrast with 
“programmed operator”). 


unprotected field. A field that is available for 
the operator to enter or modify data. 


valid key. A key that is recognized by the host 
session. 
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Appendix G. Alternate Code Page 
Support 


EEHLLAPI, using DOS 3.30, has Code Page 
Support for the following countries: 


Supported Code Pages 


437, 850 
437, 850 
863, 850 
865, 850 
437, 850 
437, 850 
437, 850 
437, 850 
437, 850 
865, 850 
860, 850 
437, 850 
437, 850 
437, 850 
437, 850 
437, 850 
437, 850 
437, 850 
437, 850 


Figure G-1. Supported Code Pages 


Warning: If you configure DOS for a language 
that does not match your entry emulator 
language, the results of an ASCII translation will 
be unpredictable. 
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